Cómo depurar paso a paso una respuesta JSON de API
Un proceso repetible para separar errores de transporte, problemas de sintaxis JSON y fallos del contrato de datos en las respuestas de una API.
Una respuesta que parece JSON roto puede ser una página HTML de error, un mensaje del proxy, datos comprimidos o un contenido válido con una estructura inesperada. Depura la respuesta por capas en lugar de cambiar el cliente hasta que desaparezca el error.
Conserva una copia anonimizada del estado, las cabeceras y el cuerpo originales. Formatear demasiado pronto puede ocultar un truncamiento, problemas de codificación o el byte exacto en el que falló el análisis.
Comprueba HTTP antes de analizar JSON
Confirma el código de estado, Content-Type, Content-Encoding y el juego de caracteres. Una respuesta 200 todavía puede contener una página de inicio de sesión, mientras que un error JSON útil puede llegar con 400 o 500.
Reproduce la petición con cURL y compara el método, la URL, los parámetros, el cuerpo, la autenticación y las cabeceras Accept con el cliente que falla.
Separa la sintaxis del contrato de datos
Formatea el cuerpo intacto. Si no se puede analizar, busca comas finales, comillas sin escapar, caracteres de control, resultados parciales y texto antes o después del documento JSON.
Si el análisis funciona, valida los campos obligatorios, los valores nulos, los tipos numérico y textual, las enumeraciones y las matrices anidadas contra el esquema documentado.
Compara una respuesta que funcione
Compara la respuesta fallida con un ejemplo válido anonimizado después de eliminar identificadores y marcas de tiempo variables. Los cambios estructurales suelen importar más que los espacios o el orden de las claves.
{:"Registra la entrada mínima que reproduce el problema y la capa que lo introdujo"=>"cliente, aplicación, proxy, CDN o servicio externo."}
Lista de depuración de respuestas API
- Guarda estado, cabeceras y cuerpo originales.
- Verifica Content-Type y codificación.
- Reproduce la petición fuera del cliente que falla.
- Valida la sintaxis JSON por separado del esquema de la API.
- Compara tipos, valores nulos, campos obligatorios y forma de las matrices.
- Elimina tokens y datos personales antes de compartirla.
Guías relacionadas
Aprenda el workflow detrás de esta herramienta y qué revisar después.
Cómo depurar payloads JSON de API
Un workflow práctico para formatear JSON, encontrar errores de sintaxis, validar la forma del payload y revisar el status cuando los datos de API no cuadran.
Cómo depurar autenticación JWT de forma segura
Un proceso orientado a la seguridad para separar la estructura del token, la validación de declaraciones, la verificación de la firma y las decisiones de autorización.
Cómo limpiar un CSV antes de importarlo
Un proceso seguro de limpieza que conserva el archivo original y convierte los supuestos de importación en verificaciones explícitas.