«Unexpected token» es el mensaje de error más inútil del desarrollo web: solo dice que algo, en algún sitio, no está bien. En la práctica, casi todos los errores de JSON tienen seis causas, y quien las conoce encuentra el problema en segundos. Esta guía las muestra con ejemplos, explica qué no permite JSON a diferencia de JavaScript y cómo encontrar lo que necesitas en una respuesta de API de 5.000 líneas. Conocer los errores de JSON más comunes permite encontrar el fallo en segundos.
Qué es JSON y qué no es
JSON es un formato de datos con muy pocas reglas: objetos entre llaves, arrays entre corchetes, claves siempre entre comillas dobles, valores que son cadenas, números, true/false/null, objetos o arrays. Todo lo que JavaScript permite además —comentarios, comillas simples, funciones, undefined, comas finales— está prohibido en JSON. De ahí salen los errores.
Las seis causas de los errores de JSON
- Coma final.
{"a": 1, "b": 2,}: la coma tras el último elemento no es válida. - Comillas simples.
{'nombre': 'Ana'}: JSON solo admite dobles. - Claves sin comillas.
{nombre: "Ana"}: válido en JavaScript, no en JSON. - Comentarios.
// notao/* ... */no existen en JSON. Los archivos de configuración que admiten comentarios son JSON5 o JSONC, no JSON. - Caracteres sin escapar dentro de una cadena. Un salto de línea o unas comillas dentro de una cadena deben escribirse como
no". - Datos truncados. La respuesta se cortó al copiar; el analizador dice «Unexpected end of input». Comprueba que la última llave esté.
Pega el texto en el formateador de JSON: marca la línea y la columna del error y nombra la causa en lenguaje claro.
Números que no lo son
Los ceros iniciales (007), los hexadecimales (0xFF), NaN e Infinity no son válidos. Los enteros muy grandes (más de 2^53) pierden precisión en JavaScript: transmite los ID como cadenas.
Hacer legibles los archivos grandes
Nadie lee de arriba abajo una respuesta de 5.000 líneas. La vista de árbol del formateador pliega y despliega objetos, la búsqueda encuentra claves en toda la estructura y la ruta a cada valor (data.items[3].price) se puede copiar, justo lo que necesitas en el código.
Formatear frente a minificar
Formateado (con sangría) es JSON para personas; minificado (sin espacios) es para transmitir. Son los mismos datos; minificado ahorra un 20–40 % en respuestas grandes. En archivos de configuración y repositorios Git guárdalo siempre formateado: los diffs se leen mejor.
Preguntas frecuentes
¿Por qué la consola del navegador acepta mi JSON y el servidor no?
Porque en la consola escribes un literal de objeto JavaScript, no JSON. El servidor analiza de forma estricta.
¿Cómo valido JSON en la terminal?
cat archivo.json | python3 -m json.tool lo formatea y señala los errores con su posición.
¿Importa el orden de las claves?
Según la especificación, no. Si tu código depende de él, es frágil.
Gratis, funciona en tu navegador, no se sube nada, sin registro.
Sigue leyendo
Más de Herramientas para desarrolladores.
