10 erros clássicos ao depurar JSON (e como corrigir rápido)

JSON quebrado raramente é mistério — é padrão. Depois que você reconhece os mesmos erros voltando, para de caçar fantasma em log e começa a consertar estrutura, encoding e suposições em minutos. Quando a API devolve Unexpected token ou um pipeline derruba config, o culpado raramente é "JSON em si": muitas vezes você alimentou o parser com texto que parece JSON no editor mas viola regras claras (RFC 8259). E formatar e inspecionar localmente no Safe Local Tools evita mandar segredos para servidores de formatter na internet.

Por que "funciona no Node" e falha em parser estrito

Desenvolvedores confundem literais JavaScript com JSON. JavaScript tolera vírgulas finais, aspas simples e alguns atalhos; JSON é gramática apertada para troca de dados. O bug nasce no protótipo que nunca serializou, e explode quando grava disco ou HTTP.

Também há o fator chat: snippets colados em apps que trocam aspas tipográficas ou espaços invisíveis. Trate payload como evidência — preserve bytes, compare formas normalizadas.

Erro 1 — vírgula após a última propriedade

Vírgula final é válida em muito JS moderno; não é válida em JSON estrito. Editores bonitos escondem o problema. Geradores de template muitas vezes emitem vírgulas sobrando quando o último campo mudou — automatize JSON.parse em fixtures de CI.

{
  "userId": 42,
  "role": "editor",
}

Erros 2 a 5 — aspas, controle, tipos JSON e chaves duplicadas

Aspas simples envolvendo chaves/valores são inválidas; JSON exige aspas duplas. Caracteres de controle crus dentro de string quebram — use \n ou serialize de verdade. undefined, NaN, Infinity não são tokens JSON; mapeie para null, strings ou omita chaves.

Chaves duplicadas podem ser aceitas dependendo do loader, com primeiro ou último valor ganhando — comportamento não determinístico entre stacks. Trate como bug de esquema e audite com modo estrito.

const reparado = JSON.stringify({ status: "ok" });

Erros 6 a 10 — comentários, encoding, payloads gigantes, drift e vazamento

JSON puro não tem comentários; JSONC só onde a ferramenta promete. BOM e encodings mistos quebram no caractere zero — normalize UTF‑8 sem BOM vindos de Excel ou legado. JSON enorme e pretty‑printed infla banda e Diffs — minifique no fio, pretty só para humanos.

Drift de esquema (userId número virando string) quebra consumidores estritos silenciosamente em outro sentido. Por fim, depurar cole tokens e PII em tíquetes — por isso ferramenta local importa.

Safe Local Tools processa JSON no navegador: ideal para iterar em payloads redigidos sem ampliar superfície desnecessária.

Fluxo de depuração que termina

Capture os bytes exatos que falharam. Localize a posição reportada. Reduza o documento por busca binária até o menor trecho que falha. Valide contra JSON Schema ou OpenAPI se existir. Depois de corrigir, passe de novo pelo serializador de produção — muitos bugs são double‑stringify, não erro visual no editor.

Guarde fixtures dourados com unicode, arrays aninhados e extremos numéricos; rode parse em upgrades de dependência.

Interop entre linguagens

Inteiros enormes podem perder precisão em JavaScript mesmo com JSON válido. Objetos JSON são não ordenados conceitualmente, mas humanos confiam em ordem de inserção. Datas precisam ISO‑8601 com fuso explícito. SDKs "ajudados" que coergem tipos mascaram payloads ruins até um ramo raro explodir — prefira falhar cedo na borda.

Integrações via Slack, Teams ou e‑mail frequentemente transformam aspas tipográficas, stripam indentação ou quebram linhas — o payload que você cola deixa de ser o que o microserviço recebeu. Ao depurar, peça o dump bruto do corpo HTTP ou do arquivo em disco; formatadores públicos incentivam o hábito de jogar segredos em log compartilhado.

Por isso um validador no navegador, como o fluxo do Safe Local Tools, encaixa em squads que trabalham com tokens de API e chaves efêmeras: você cola uma cópia redigida localmente, itera até JSON.parse sorrir, e só então reintroduz valores reais via Secret Manager — sem passar o arquivo completo por um backend de terceiro que não está no DPA.

Quando fixtures crescem, automatize JSON.parse em CI e dif estatístico de tamanho: regressões de serialização aparecem como picos de bytes antes de virarem erro de parsing em produção.

Quando você sabe o que quebra JSON, o trabalho vira mecânica: citar corretamente, remover tokens ilegais, validar tipos e comparar antes/depois. Sem enviar dados sensíveis para fora da máquina, Experimentar o formatador de JSON →