Un parser que dice “invalid JSON” está informando un síntoma, no una causa completa. A veces falta una coma o sobra una comilla. En aplicaciones reales, el problema también puede ser una respuesta HTML servida por un proxy, un archivo truncado, un charset incorrecto, un byte invisible, un número fuera de rango o un cliente que envió un tipo distinto al documentado. Depurar bien requiere mirar bytes, headers y contrato, no solo pegar el texto en un formatter.

Primero verifica qué llegó realmente

Antes de corregir el productor, captura la respuesta o request exacto. Herramientas de red, logs seguros o fixtures pueden mostrar si el cuerpo está completo, si contiene HTML de error, si llega comprimido, si el content type es correcto y si hay caracteres antes del primer { o [. Muchos errores nacen fuera del JSON en sí.

Un backend puede devolver una página de login, un gateway puede insertar un mensaje, o una excepción puede producir texto plano. El cliente solo sabe que esperaba JSON y recibió otra cosa. Revisar status code y headers evita perseguir una coma que no existe.

Los strings son una fuente común de fallos

En JSON, las strings deben usar comillas dobles y escapar ciertos caracteres. Saltos de línea reales dentro de una string, comillas sin escapar o backslashes mal duplicados rompen el documento. El error puede aparecer lejos del lugar donde se construyó el valor, especialmente cuando se concatena JSON manualmente.

La solución estable es no construir JSON con concatenación. Un serializer conoce las reglas de escaping y reduce errores. Si hay que inspeccionar un caso, conviene buscar caracteres de control, comillas y secuencias Unicode incompletas.

Encoding y BOM pueden confundir

JSON moderno se espera normalmente en UTF-8. Un archivo guardado con otro encoding o con un byte order mark inesperado puede fallar en parsers estrictos. También pueden aparecer caracteres invisibles al copiar desde documentos, hojas de cálculo o herramientas de oficina.

Cuando el texto parece correcto, revisar bytes con una herramienta hexadecimal puede ser más útil que mirarlo en un editor. La pregunta no es solo “qué veo”, sino “qué bytes recibió el parser”.

Trailing commas y comentarios no pertenecen a JSON estricto

Muchos desarrolladores vienen de JavaScript, donde ciertos entornos permiten comas finales o comentarios en objetos. JSON estricto no los permite. Algunos parsers tolerantes los aceptan, otros no. Esa diferencia puede explicar por qué un archivo funciona localmente y falla en producción.

Si el formato es para configuración humana, quizá JSON5 o YAML sean opciones válidas. Si es un contrato entre sistemas, mantener JSON estricto evita que consumidores tengan que imitar extensiones no estándar.

Los números grandes pueden ser válidos y aun así peligrosos

Un documento puede ser JSON válido y perder datos al parsearse. Identificadores grandes enviados como numbers pueden redondearse en entornos con precisión limitada. Decimales financieros pueden sufrir errores si se tratan como floating point. El parser no necesariamente falla; el bug aparece después.

Para depurar, compara el texto original con el modelo deserializado. Si el valor cambia, el problema no era sintaxis sino tipo. IDs y cantidades exactas suelen necesitar strings o formatos específicos.

El truncamiento produce errores engañosos

Una respuesta cortada por timeout, límite de tamaño o cierre de conexión puede parecer JSON casi válido hasta el final. El parser acusará un array sin cerrar o una string incompleta. La causa real está en transporte, buffering o límites de infraestructura.

Registrar longitud esperada, longitud recibida y request ID ayuda a identificar patrones. Si solo ciertos payloads grandes fallan, revisa límites de proxy, servidor, cliente y cola antes de modificar la lógica de serialización.

Validez sintáctica no garantiza validez de contrato

Un JSON puede parsearse perfectamente y aun así ser incorrecto para la API: falta un campo requerido, el tipo no coincide, una fecha no tiene timezone o un enum usa un valor desconocido. Esos errores deben producir mensajes de validación distintos de “invalid JSON”.

Separar parse errors de schema errors mejora la experiencia de integración. El cliente sabe si debe arreglar sintaxis, encoding o contenido de dominio. Los logs también se vuelven más útiles para soporte.

Haz reproducible el caso mínimo

Una vez capturado el payload exacto, reduce el documento hasta encontrar el fragmento que rompe. Mantén el mismo encoding y no dejes que un formatter “repare” el texto antes de probar. Si el bug depende de transporte, conserva headers y tamaño.

Los casos reproducibles deben convertirse en tests. Un fixture con el payload problemático evita que el mismo bug vuelva cuando cambie la biblioteca JSON, el framework HTTP o el generador de respuestas.

La prevención es mejor que el formateo manual

Usa serializers mantenidos, content types explícitos, límites de tamaño, schemas, pruebas de contrato y logs que distingan errores de sintaxis y de dominio. Evita concatenar JSON, aceptar extensiones no documentadas o corregir payloads silenciosamente.

Depurar JSON inválido es más rápido cuando el sistema trata el formato como un contrato completo: bytes correctos, encoding correcto, sintaxis estricta y significado validado. Un formatter ayuda, pero no reemplaza esa disciplina.