¿Qué hacer si el decodificador JWT da error de token inválido? Primero veamos la conclusión
Si te encuentras con un error del decodificador JWT, no te apresures a cambiar el código. Más del noventa por ciento de los "tokens inválidos" no se deben a un problema con el algoritmo de cifrado, sino a que el token en sí está incompleto, se mezclaron caracteres adicionales al pegarlo, o confundiste "decodificar" con "validar". Siguiendo el orden a continuación, normalmente podrás localizarlo en unos minutos.
El decodificador JWT es solo una herramienta de análisis local; restaura las tres secciones del token en encabezado y carga útil legibles. No verifica la firma ni determina si el token ha expirado.
Cómo usar el decodificador JWT: análisis en tres pasos
Un JWT válido consta de tres partes separadas por dos puntos ingleses: encabezado, carga útil y firma. Si falta cualquiera de ellas, el análisis fallará.
- Obtén la cadena completa del token, que suele aparecer en el campo
Authorizationdel encabezado de la solicitud, con el formatoBearer. - Elimina el prefijo
Bearery los espacios sobrantes, conservando solo el token en sí. - Pégalo en el Decodificador JWT; la herramienta restaurará el encabezado y la carga útil localmente en el navegador.
En el resultado del análisis verás campos como alg, exp, sub, etc. exp es la marca de tiempo de expiración, en segundos.
Errores comunes al usar el decodificador JWT
El error más frecuente es pegar todo el encabezado de la solicitud, incluyendo Bearer y saltos de línea. Los saltos de línea son invisibles a simple vista, pero hacen que la decodificación base64url falle directamente.
El segundo error es truncar el final al copiar. El token es muy largo, y los programas de mensajería y las terminales a menudo insertan saltos de línea o puntos suspensivos en medio.
El tercer error es usar pegado con formato enriquecido, donde las comillas se convierten automáticamente en caracteres chinos de ancho completo.
Qué hacer si el decodificador JWT da error: revisa estas cinco categorías de causas
A continuación se ordenan de mayor a menor frecuencia; puedes compararlas una por una.
- Número de segmentos incorrecto: el token debe tener exactamente dos puntos separadores; uno de más o de menos provocará error.
- Conjunto de caracteres no válido: base64url solo permite letras, números,
-y_; si aparecen+,/,=o espacios, hay que sospechar. - Caracteres en blanco: espacios al inicio y final, tabulaciones y saltos de línea rompen el análisis.
- Token truncado: la longitud es claramente demasiado corta, o el final no es un segmento completo.
- El contenido en sí no es un JWT: por ejemplo, algunas API devuelven tokens opacos que no se pueden analizar en absoluto.
Por qué eliminar el prefijo Bearer resuelve la mayoría de los errores
Porque el decodificador necesita el token puro, y Bearer es parte del protocolo de transporte, no de la estructura del token. Al mezclar ambos, el primer segmento deja de ser una cadena base64url válida.
Si encuentras errores repetidamente en escenarios de depuración de API con el decodificador JWT, se recomienda guardar primero la cadena original en un archivo de texto plano, eliminar los espacios al inicio y final, y luego pegarla; así se descarta la interferencia de los saltos de línea automáticos del editor.
Diferencia entre decodificador JWT y validación
Este es el punto más fácil de confundir y la raíz de muchos "falsos positivos".
Decodificar solo restaura la codificación base64url a texto plano; cualquier cadena que cumpla el formato se puede decodificar, sin necesidad de clave. Validar, en cambio, requiere verificar si la firma fue generada por quien posee la clave, y comprobar la expiración, el emisor, la audiencia y otras declaraciones.
Por lo tanto, decodificar con éxito no significa que el token sea válido. Un token manipulado también se puede decodificar, pero la validación fallará con seguridad.
A la inversa, un fallo de decodificación normalmente indica que los datos se corrompieron durante la transmisión o copia, no que la firma tenga problemas. Distinguir estas dos cosas te ahorrará mucho tiempo de diagnóstico.
Decodificador JWT y archivos grandes: cómo manejar tokens muy largos
El JWT tiene un límite de tamaño, pero al incluir muchas declaraciones personalizadas en la carga útil, el token se vuelve muy largo, algo común en escenarios con listas de permisos o perfiles de usuario.
Los tokens largos traen dos problemas. Primero, al copiarlos las herramientas tienden a dividir líneas automáticamente; segundo, algunas terminales y sistemas de registro truncan cadenas demasiado largas.
Recomendaciones de manejo:
- Primero escribe el token en un archivo con un comando o script, y luego revisa segmento por segmento si está completo.
- Confirma que no se hayan mezclado saltos de línea; muchos errores provienen de esto.
- Si la carga útil es realmente demasiado grande, considera simplificar los campos de declaración y conservar solo la información necesaria.
Cabe recordar que cuanto más largo es el token, mayor es la sobrecarga adicional en cada solicitud. Esto no es solo un problema de decodificación, también afecta el rendimiento de la API.
Decodificador JWT en móvil: puntos clave de diagnóstico en dispositivos móviles
Diagnosticar problemas de token en el móvil tiene su principal dificultad en copiar y pegar.
La selección por pulsación larga en móvil fácilmente omite algunos caracteres del inicio o del final. Se recomienda usar "Seleccionar todo" en lugar de arrastrar manualmente el cuadro de selección.
Además, algunos teclados reemplazan automáticamente las comillas inglesas por comillas chinas, o añaden un espacio después de las mayúsculas. Antes de pegar, cambia al estado de entrada en inglés.
Si la página de tu sitio de herramientas también se renderiza correctamente en móvil, basta con pegar directamente; el proceso de análisis se completa localmente y el token no sale de tu dispositivo. Esto es especialmente importante al diagnosticar tokens en entornos de producción.
Preguntas frecuentes
La decodificación es exitosa pero la API sigue devolviendo 401, ¿es problema del decodificador?
No. Un 401 normalmente significa que la validación del servidor no pasó; la causa puede ser que la firma no coincide, que el token expiró, o que el emisor y la audiencia no coinciden. El decodificador solo se encarga de restaurar el contenido, no participa en la validación.
¿Por qué aparecen caracteres ilegibles en el token?
Generalmente es por un conjunto de caracteres no válido o por caracteres ocultos. base64url usa un rango de caracteres muy limitado; si se mezclan espacios, saltos de línea o símbolos de ancho completo, el resultado restaurado serán caracteres ilegibles.
¿Por qué el mismo token se podía decodificar ayer y hoy no?
La cadena del token en sí no cambia. Es más probable que el contenido que copiaste esta vez sea diferente al anterior, por ejemplo con un salto de línea extra, o que el campo devuelto por la API de origen haya cambiado.
¿El decodificador puede ver la clave correspondiente a la firma?
No. La firma es el resultado de una operación unidireccional; no se puede deducir la clave a partir de ella. Cualquier afirmación de que se puede recuperar la clave desde el token no es confiable.
¿Cómo se lee la hora de expiración?
exp e iat son marcas de tiempo Unix, en segundos, y deben convertirse a fecha para compararlas. Ten en cuenta que representan hora UTC.
Cierre
Para diagnosticar qué hacer cuando el decodificador JWT da error, el núcleo son tres pasos: confirmar que el token está completo, eliminar los caracteres que no son del token, y distinguir decodificación de validación. Si haces bien estas tres cosas, la gran mayoría de los errores desaparecerán. Cuando necesites verificar sobre la marcha, puedes usar la herramienta que se ejecuta localmente en el navegador para restaurar rápidamente el contenido del token; el proceso de diagnóstico no requiere subir ningún dato.