Como depurar payloads JSON de API
Um workflow prático para formatar JSON, encontrar erros de sintaxe, validar o formato do payload e revisar o status quando dados de API parecem errados.
Problemas de JSON API muitas vezes começam como bugs frontend vagos: campo ausente, null inesperado, data inválida, tipo incorreto ou body que nem é JSON válido.
O fluxo mais rápido separa problemas de transporte e de dados. Primeiro revise status HTTP e headers, depois se o body é JSON válido, e então valide o formato contra o contrato esperado.
Formate e inspecione o payload
Pretty formatting facilita revisar objetos e arrays aninhados. Também ajuda a revelar respostas truncadas, campos suspeitos ou strings com JSON escapado.
Se o payload não parseia, revise trailing commas, aspas inválidas, comments, caracteres de controle não escapados ou uma página HTML de erro retornada no lugar de JSON.
Valide o formato esperado
Um payload pode ser JSON válido e ainda estar errado para a app. Schema validation detecta required fields ausentes, tipos errados, enum values inesperados e mudanças de estrutura.
Quando o backend muda um campo de number para string ou retorna null onde a UI espera object, schema validation geralmente aponta a diferença exata.
Revise status codes e conversões
Não depure o body sem revisar o status HTTP. Um 401, 403, 404, 422 ou 500 pode explicar por que o payload não combina com o happy path.
Ao converter entre JSON e YAML ou arquivos de configuração, verifique que arrays, booleanos, nulls e strings quoted preservem o significado esperado.
Checklist para depurar JSON API
- Revise primeiro status HTTP, content type e response headers.
- Formate o JSON antes de inspecionar dados aninhados.
- Valide o payload contra o schema ou contrato esperado.
- Procure nulls, campos ausentes, tipos errados e enum values alterados.
- Confirme que conversões preservem booleanos, arrays, nulls e strings.
Guias relacionados
Entenda o workflow por trás desta ferramenta e o que revisar depois.
Como depurar respostas JSON de API
Formate a resposta, confirme o status HTTP, valide o schema e compare mudanças do payload antes de alterar código.
Como inspecionar problemas de autenticação JWT
Fluxo JWT para revisar claims, time values, permissões e signing assumptions sem tratar decode como verification.