Errores comunes en JSON y cómo solucionarlos

Por qué falla un JSON

JSON es un estándar estricto. A diferencia de “objetos estilo JavaScript”, JSON no admite tolerancias: si la sintaxis no es perfecta, el parser no puede convertir ese texto a una estructura de datos y la aplicación devuelve error. En APIs, suele verse como 400 Bad Request, invalid JSON o un mensaje similar.

Lo más frustrante es que muchas veces el JSON es largo, y un error mínimo puede estar escondido. Por eso, una buena estrategia es: validar, formatear y recién después revisar.

Los 12 errores más comunes en JSON (con ejemplos y solución)

1) Usar comillas simples en lugar de dobles

Inválido:

{'name': 'Ivan'}

Válido:

{"name": "Ivan"}

2) Dejar una coma final

Inválido:

{"a": 1, "b": 2,}

Solución: elimina la coma final.

3) Llaves o corchetes sin cerrar

Inválido:

{"a": {"b": [1,2,3]}

Solución: cierra correctamente: }} o ] según corresponda.

4) Comentarios dentro del JSON

Inválido:

{
  "a": 1 // comentario
}

JSON no admite comentarios. Si necesitas documentar, hazlo fuera del JSON.

5) Booleanos mal escritos

Inválido: {"ok": True} o {"ok": FALSE}

Válido: {"ok": true} o {"ok": false}

6) Null mal escrito

Inválido: {"value": NULL}

Válido: {"value": null}

7) Strings sin comillas

Inválido:

{"country": Spain}

Válido:

{"country": "Spain"}

8) Claves sin comillas

Inválido: {name: "Ivan"}

Válido: {"name": "Ivan"}

9) Números con formato no permitido

JSON admite números, pero algunos formatos raros pueden fallar según el parser. Por ejemplo, 01 como entero puede interpretarse mal en ciertos contextos.

Recomendación: usa 1 en lugar de 01 (salvo que sea string).

10) Caracteres especiales sin escape

En strings, ciertos caracteres deben ir escapados. Por ejemplo una comilla dentro de un texto:

Inválido:

{"text": "El usuario dijo "hola""}

Válido:

{"text": "El usuario dijo "hola""}

11) Mezclar arrays y objetos sin querer

A veces se espera un array ([]) pero se envía un objeto ({}) o viceversa. Eso no siempre rompe el JSON, pero rompe la integración.

Ejemplo: si la API espera "items": [] y envías "items": {}, puede devolver error.

12) Payload demasiado grande o con campos no esperados

Aunque el JSON sea válido, algunas APIs limitan tamaño o validan campos permitidos. Si te devuelve error con JSON válido, revisa documentación: límites, campos requeridos y tipos.

Cómo interpretar mensajes de error típicos

Dependiendo del lenguaje o servidor, verás mensajes diferentes. Ejemplos:

• Unexpected token: suele indicar una coma extra, una comilla mal o un carácter inesperado.
• Expected '}': falta cerrar una llave.
• Trailing comma: coma final no permitida.
• Malformed JSON: genérico; casi siempre es sintaxis.

Consejo práctico: si formateas el JSON (pretty print), las llaves y corchetes se alinean y es más fácil ver qué falta o qué sobra.

Checklist práctico antes de enviar JSON

1. ¿Todas las claves y strings tienen comillas dobles?
2. ¿No hay comas finales?
3. ¿Están cerradas todas las llaves y corchetes?
4. ¿Los booleanos son true/false y null es null?
5. ¿No hay comentarios?
6. ¿La estructura coincide con lo esperado por la API? (array vs objeto)

Validar y formatear JSON online (la forma más rápida)

Para salir de dudas en segundos, pega el texto en nuestro Validador y Formateador de JSON. Te indicará si es válido, mostrará errores de forma legible y te devolverá el JSON formateado o minificado listo para copiar.

Esto es especialmente útil cuando estás trabajando con:

• Webhooks y callbacks
• Respuestas REST
• Configuraciones de apps
• Logs y depuración de incidencias

Preguntas frecuentes

¿Cómo sé si mi JSON es válido sin herramientas?

Puedes intentar parsearlo en tu lenguaje (por ejemplo json_decode en PHP), pero para una comprobación rápida es más cómodo un validador.

¿Por qué mi JSON “parece” correcto y aún falla?

Puede ser un problema de estructura (tipo esperado), campos obligatorios o límites de tamaño. Primero valida la sintaxis, luego revisa contrato/documentación.

Recomendación final: valida siempre con nuestro validador antes de enviarlo a producción.

Flujo de depuración recomendado (paso a paso)

Cuando recibes un error por JSON, lo peor es corregir “a ojo” sin un método. Este flujo te ahorra tiempo:

1. Validar sintaxis: primero asegúrate de que sea JSON válido.
2. Formatear (pretty): alinear llaves y corchetes para detectar dónde se rompe.
3. Buscar el punto exacto: si el error indica token inesperado, revisa el carácter previo.
4. Confirmar tipos: después de sintaxis, revisa que el contrato sea correcto (array vs objeto, números vs strings).
5. Minificar (opcional): solo al final, si necesitas reducir tamaño.

Puedes hacer los pasos 1 y 2 en segundos usando el Validador y Formateador de JSON.

Errores avanzados: el JSON es válido pero la API lo rechaza

A veces el JSON es correcto pero el servidor responde con error. En ese caso no es “JSON inválido”, sino validación de negocio o de contrato. Estos son los motivos más comunes:

Campo obligatorio faltante

El parser lo acepta, pero la API espera un campo requerido. Ejemplo: falta "email" o "id".

Tipo incorrecto

El servidor espera número y recibe string, o viceversa. Ejemplo: {"qty":"2"} en lugar de {"qty":2}.

Estructura distinta (array vs objeto)

Muchas integraciones fallan porque un campo cambia de forma. Si hoy envías items: [] y mañana items: {}, el cliente se rompe.

Fechas con formato no aceptado

JSON no tiene fechas nativas. Asegúrate de usar un formato consistente (por ejemplo ISO 8601) y el timezone esperado.

Problemas de codificación

En sistemas antiguos, caracteres especiales pueden romper validaciones (acentos, emojis). Asegúrate de usar UTF-8.

Consejo: valida el JSON y, además, compara tu payload con el ejemplo oficial de la API. Si estás documentando, incluye un ejemplo formateado (pretty) para evitar malentendidos.

Tabla rápida de diagnóstico

Más preguntas frecuentes

¿Por qué algunos validadores aceptan comas finales?

Algunas herramientas son “permisivas” para ayudarte a editar, pero eso no significa que sea JSON estándar. En producción, un parser estricto fallará.

¿Cómo evito que se cuelen errores al copiar/pegar?

Siempre valida antes de enviar. Un validador también te permite formatear, lo que reduce el riesgo de errores invisibles.

¿Qué hago si el JSON viene dentro de un string (doble parseo)?

Es común en algunos logs o APIs: un campo contiene una cadena que a su vez es JSON. En ese caso debes decodificar dos veces (con cuidado) y validar en cada paso.

Ejemplos en PHP: detectar el error exacto

Si estás en backend con PHP, puedes validar rápidamente un JSON usando json_decode y revisando json_last_error(). Esto es útil para registrar un error detallado en logs cuando un cliente envía un payload inválido.

$raw = file_get_contents("php://input");
$data = json_decode($raw, true);

if (json_last_error() !== JSON_ERROR_NONE) {
  error_log("JSON inválido: " . json_last_error_msg());
  http_response_code(400);
  echo json_encode(["ok" => false, "error" => json_last_error_msg()]);
  exit;
}

Aun así, cuando estás depurando manualmente, es más rápido pegar el texto en un validador, porque además te lo formatea y lo deja listo para copiar.

Errores “invisibles” al copiar y pegar

Hay dos casos comunes que parecen magia negra:

• Comillas tipográficas (curly quotes): se ven como comillas normales, pero no lo son.
• Espacios no separables: algunos editores insertan caracteres especiales que rompen parsers estrictos.

Solución práctica: pega el JSON en el validador, formatea y copia desde la salida. Si el JSON era inválido, verás el error de inmediato.

Conclusión

La mayoría de errores en JSON son simples, pero consumen tiempo cuando el payload es grande. Con un método (validar → formatear → revisar) y una herramienta adecuada, los resuelves rápido.

Guarda este link: Validador y Formateador de JSON. Te ahorrará tiempo cada vez que trabajes con APIs o integraciones.

Lista de comprobación extendida para integraciones

Si trabajas con integraciones reales (clientes, proveedores, sistemas legacy), esta lista te ayuda a reducir incidencias:

• Headers correctos: usa Content-Type: application/json al enviar JSON.
• Encoding: asegúrate de que todo sea UTF-8 (especialmente si hay acentos).
• Campos opcionales: decide si omites campos o los envías como null; mantén consistencia.
• IDs como string: si hay riesgo de perder precisión en clientes JS, envía IDs grandes como texto.
• Versionado: si vas a cambiar estructura, versiona el endpoint o incluye un campo de versión.
• Logs: registra el request en modo seguro (sin datos sensibles) cuando haya error.

En soporte, el 80% de los tickets se resuelve comparando “lo esperado” contra “lo que llegó”. Por eso es clave poder formatear y leer el JSON rápidamente.

FAQ extra para equipos

¿Debo aceptar JSON con campos desconocidos?

Depende. Si quieres compatibilidad futura, puedes ignorarlos. Si necesitas seguridad o control estricto, recházalos. Lo importante es documentarlo.

¿Qué hago si recibo un array cuando esperaba un objeto?

Si el contrato no lo permite, responde 400 con un mensaje claro. Evitarás datos inconsistentes en tu sistema.

¿Cómo preparo un ejemplo mínimo reproducible?

Toma el payload real, elimina campos irrelevantes y valida que siga reproduciendo el error. Formatea el resultado para que otros lo puedan leer en segundos.