Como depurar uma resposta JSON de API passo a passo
Um processo repetível para separar erros de transporte, problemas de sintaxe JSON e falhas do contrato de dados nas respostas de uma API.
Uma resposta que parece JSON quebrado pode ser uma página HTML de erro, uma mensagem do proxy, dados comprimidos ou um conteúdo válido com estrutura inesperada. Depure a resposta por camadas em vez de alterar o cliente até o erro desaparecer.
Preserve uma cópia anonimizada do status, dos cabeçalhos e do corpo originais. Formatar cedo demais pode ocultar truncamentos, problemas de codificação ou o byte exato em que a análise falhou.
Verifique HTTP antes de analisar JSON
Confirme o código de status, Content-Type, Content-Encoding e o conjunto de caracteres. Uma resposta 200 ainda pode conter uma página de login, enquanto um erro JSON útil pode chegar com 400 ou 500.
Reproduza a requisição com cURL e compare método, URL, parâmetros, corpo, autenticação e cabeçalhos Accept com o cliente que apresenta a falha.
Separe a sintaxe do contrato de dados
Formate o corpo intacto. Se a análise falhar, procure vírgulas finais, aspas sem escape, caracteres de controle, resultados parciais e texto antes ou depois do documento JSON.
Se a análise funcionar, valide campos obrigatórios, valores nulos, tipos numéricos e textuais, enumerações e matrizes aninhadas de acordo com o esquema documentado.
Compare uma resposta que funciona
Compare a resposta com falha a um exemplo válido anonimizado após remover identificadores e horários variáveis. Mudanças estruturais costumam ser mais importantes que espaços ou a ordem das chaves.
{:"Registre a menor entrada que reproduz o problema e a camada que o introduziu"=>"cliente, aplicação, proxy, CDN ou serviço externo."}
Checklist de resposta da API
- Salve status, cabeçalhos e corpo originais.
- Verifique se Content-Type e codificação correspondem ao corpo.
- Reproduza a requisição fora do cliente com falha.
- Valide a sintaxe JSON separadamente do esquema da API.
- Compare tipos, valores nulos, campos obrigatórios e formato das matrizes.
- Remova tokens e dados pessoais antes de compartilhar.
Guias relacionados
Entenda o workflow por trás desta ferramenta e o que revisar depois.
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.
Como depurar autenticação JWT com segurança
Um processo atento à segurança para separar estrutura do token, validação de declarações, verificação de assinatura e decisões de autorização.
Como limpar CSV antes da importação
Um processo seguro de limpeza que preserva o arquivo original e transforma as suposições de importação em verificações explícitas.