Cómo leer y depurar respuestas JSON de una API
Cuando una integración falla, la respuesta suele estar en el cuerpo de la respuesta. Esta guía explica cómo capturarla, hacerla legible y encontrar los campos que aclaran qué salió mal.
Abrir la herramienta: Formateador JSON para respuestas API
1. Captura la respuesta completa
Usa la pestaña Red de las herramientas de desarrollo para las peticiones que hace una página web, y curl para todo lo demás. curl -i muestra el código de estado y las cabeceras además del cuerpo, y eso a menudo explica un error antes incluso de leer el JSON.
Copia la respuesta entera. Una respuesta cortada de un log o de la terminal no se puede formatear, porque faltan los cierres.
2. Mira primero el código de estado
| Estado | Significado | Qué buscar en el cuerpo |
|---|---|---|
| 200, 201 | Éxito | Los datos que pediste o creaste |
| 400, 422 | La petición no era válida | Una lista de campos y mensajes de validación |
| 401, 403 | Falta permiso o no es suficiente | Pistas sobre el token o el alcance |
| 404 | No encontrado | Si la ruta o el ID son incorrectos |
| 429 | Demasiadas peticiones | Tiempo de espera o detalles del límite |
| 500 a 504 | Error del servidor o de la pasarela | Un ID de petición para el proveedor de la API |
3. Hazla legible
Pega la respuesta en el formateador JSON. Si empieza con cabeceras o un callback JSONP, se eliminan. Si ves muchas secuencias \", el JSON se codificó dos veces y el formateador lo decodifica.
Cambia a la vista de árbol y pliega los arrays grandes. La mayoría de las API envuelven los resultados en un campo como data, items o results, con los datos de paginación en meta, links o next.
4. Sigue la paginación
Las listas suelen dividirse en páginas. Busca campos como next, next_cursor, page y total. Pide la página siguiente con el cursor o la URL que te da la API en lugar de construirla tú, porque los cursores pueden cambiar entre llamadas.
5. Cuidado con números y fechas
Los ID de más de 15 o 16 cifras pueden redondearse en JavaScript. Usa la versión en texto del ID si la API la ofrece. Las fechas suelen ser textos ISO 8601 como 2026-01-15T09:30:00Z, donde Z significa UTC, así que conviértelas a la hora local solo al mostrarlas.