Como diagnosticar erros de JSON passo a passo

JSON parece simples porque tem poucos tipos de dados e pontuação familiar. Por isso um erro pequeno chega frequentemente à ferramenta como uma mensagem pouco útil: uma vírgula inesperada, uma posição ou um “token inválido”. O objetivo não é tentar alterações até o documento parar de falhar. Reduza o caso, localize a posição informada, faça uma correção compatível com a gramática e confirme que os dados mantêm o mesmo significado.

A RFC 8259 define JSON como formato de intercâmbio baseado em objetos, arrays, números, strings, booleanos e null. Nomes de objetos são strings entre aspas duplas. Uma string não pode conter uma quebra de linha literal. Vírgulas separam valores; não encerram uma lista com um separador extra. Essas regras rigorosas permitem que programas diferentes interpretem o mesmo documento.

Um parser verifica sintaxe, não intenção. Ele pode indicar onde deixou de compreender o texto, mas não sabe se dois campos com nomes diferentes são o mesmo preço, se um identificador perdeu zeros à esquerda ou se uma data tem o fuso correto. Separe o erro que impede a leitura de JSON de um problema semântico que continuará após a formatação.

Um exemplo reproduzível completo

Comece com uma cópia pequena sem segredos reais. Esta carga reúne quatro problemas comuns. A ordem importa: normalmente o parser informa o primeiro obstáculo e esconde os demais até que ele seja corrigido.

{
  "customer": "Ada",
  "items": ["notebook", "pen",],
  "note": "Deliver before
Friday",
  'orderId': "007",
  "total": 24.90,
  "amount": 24.90
}

A vírgula depois de "pen" é final. A quebra entre before e Friday está dentro de uma string sem escape. orderId usa aspas simples, aceitas em certos contextos JavaScript mas não em JSON. Por fim, total e amount são sintaticamente válidos, embora possam representar a mesma quantia. Essa última questão exige conhecer o contrato da API.

Como ler uma posição do parser

Erros de JSON.parse() podem citar posição, linha ou coluna segundo o motor e navegador. Conte desde o início da entrada exata, incluindo espaços e quebras. Não suponha que a posição seja a causa: ela marca frequentemente o caractere onde a gramática não consegue continuar. Uma vírgula final pode aparecer em ]; uma string sem escape pode aparecer na quebra de linha.

Use um editor que mostre linha e coluna. Copie o texto sem transformar aspas e evite aplicativos que adicionem espaços. Quando uma ferramenta mostra posição absoluta, observe vinte caracteres antes e depois. Quando mostra uma linha, revise também a anterior: um delimitador costuma abrir antes de surgir o sintoma.

O problema prático é distinguir uma carga ilegível de uma carga válida mas errada para o negócio. Um formatador só funciona quando a gramática está correta. Se o documento veio de um log, variável de ambiente ou resposta HTTP, preserve primeiro o original e anote qual sistema o produziu. Não substitua valores às cegas: remover um erro pode alterar assinatura, soma ou identificador. Reduza a amostra ao bloco que reproduz a falha e remova dados pessoais antes de compartilhá-la.

Diagnostique o exemplo em quatro passagens. Primeiro, vá a items: a vírgula antes de ] não separa valor algum e deve ser removida. Segundo, localize a linha de note; JSON representa a quebra com barra invertida e n, não com uma quebra física. Terceiro, troque aspas simples da chave por aspas duplas. Quarto, pergunte ao produtor se total e amount são conceitos distintos. Se forem o mesmo valor, mantenha o nome estabelecido e documente a migração.

{
  "customer": "Ada",
  "items": ["notebook", "pen"],
  "note": "Deliver before\nFriday",
  "orderId": "007",
  "total": 24.90
}

O JSON corrigido é analisado, mantém orderId como string para preservar zeros e codifica a quebra de forma portável. Não converta "007" em número apenas por parecer numérico: códigos e referências não são quantidades.

Execute primeiro o parser no ambiente que falhou, se possível. Anote mensagem e posição antes de reescrever texto. Valide uma cópia com formatador; se a mensagem mudar, verifique se a entrada foi normalizada. Corrija um único erro sintático, analise de novo e repita. Quando o resultado for válido, compare chaves, tipos, tamanhos e valores importantes com uma amostra conhecida. Para uma API, compare também com esquema ou contrato. Um esquema exige campos, mas não decide sozinho qual valor é correto.

Em automações, capture a mensagem e contexto próximo, não uma carga sensível inteira. Em JavaScript, envolva JSON.parse() em tratamento de exceção e retorne diagnóstico sem tokens. Numa integração, retenha identificador de solicitação, versão do contrato e amostra anonimizada. Isso torna o problema reproduzível sem fazer dos logs de depuração outra divulgação.

Aspas duplas, barras invertidas e vírgulas são sintaxe, não estilo opcional. Dentro de string, \n representa quebra, \" uma aspa e \\ uma barra. Uma string aberta pode fazer o parser culpar caractere posterior. Da mesma forma, uma chave ou colchete ausente pode ser informado no fim do documento, quando já é certo que o fechamento não chegou.

Chaves duplicadas exatas são especialmente arriscadas: muitos parsers mantêm a última, enquanto RFC 8259 alerta que o comportamento com nomes não únicos é imprevisível entre implementações. Duplicados semânticos como total e amount são mais difíceis: ambos podem sobreviver e gerar duas interpretações. Defina um nome canônico, rejeite a combinação ambígua no produtor e adicione teste de migração.

Evite ferramentas de “reparo” que transformam texto parecido com JavaScript em JSON sem explicar mudanças. Adicionar aspas, apagar vírgulas ou converter valores pode esconder incompatibilidade do produtor. Também não use expressões regulares para validar JSON completo: strings escapadas e aninhamento tornam esse método frágil. O parser é autoridade para sintaxe; testes de contrato e esquema cobrem o restante.

Outro erro é confundir JSON válido com resposta correta. {"enabled":"false"} é válido, mas o tipo pode precisar ser booleano. 9007199254740993 pode perder precisão ao virar número JavaScript. 03/04/2026 não explica sua ordem. Verifique tipo, unidade, fuso, intervalo e regras de negócio antes de entregar valor a outra camada.

Use dados sintéticos para aprender o fluxo e confirme onde a ferramenta processa conteúdo antes de colar informação interna. Para carga grande, divida a investigação: valide cabeçalho, um item do array e estrutura final. Não corte no meio de string ou sequência UTF-8. Preserve UTF-8 e evite processadores que substituam aspas retas por tipográficas.

Mensagens mudam entre navegadores e versões. Uma posição só é reproduzível com a entrada idêntica. Inclua versão do cliente, mensagem literal, fragmento saneado e passos de reprodução num relatório. Não publique carga inteira como exemplo se contiver e-mails, rotas internas, sessões ou contas.

Este guia não certifica que uma carga seja segura, autorizada ou adequada a decisão profissional. JSON não cifra, assina ou valida permissões. Documento bem formado pode conter instrução maliciosa, dados antigos ou números manipulados. Validação sintática não substitui autenticação, autorização, limites de tamanho, logs seguros ou revisão humana quando o contexto exige.

Ferramentas do navegador ajudam a inspecionar texto, mas não devem ser o único controle numa integração crítica. Para pagamentos, saúde, segurança, deveres legais ou dados regulados, siga contrato, procedimentos e ambientes aprovados pela organização responsável. Se não sabe o que um campo duplicado significa, interrompa a importação e consulte o proprietário dos dados.

Antes de considerar resolvido um erro JSON, guarde cópia protegida e crie exemplo mínimo sem segredos. Leia a primeira mensagem do parser e situe a posição na entrada exata. Repare uma regra de cada vez: vírgulas, aspas, escapes e fechamentos. Analise novamente após cada mudança. Quando passar, compare chaves, tipos, identificadores, números, datas e campos equivalentes com o contrato. Confirme que não há nomes duplicados ou significados sobrepostos. Por fim, teste o consumidor real com dados controlados, registre a causa e corrija o produtor para que não emita o mesmo documento outra vez.