Erros comuns de JSON e como corrigi-los
Um guia de campo sobre os erros de JSON que você vai encontrar de verdade - o que significam, de onde vêm e como corrigir rápido.
Todo desenvolvedor que trabalha com JSON acaba aprendendo suas mensagens de erro de cor. “Unexpected token in JSON at position 47” — todo mundo já olhou para essa às 3 da manhã tentando lançar uma release. As mensagens são tecnicamente corretas, mas frequentemente pouco úteis: a posição mencionada raramente é onde o erro real vive.
Este é um guia de campo sobre os erros de JSON que você vai ver na prática, o que realmente significam e como corrigir cada um rápido. Todos os exemplos foram testados contra a implementação padrão de JSON.parse() usada por todo navegador e Node.js.
1. “Unexpected token , in JSON”
O que geralmente significa: uma vírgula final.
{
"name": "Alice",
"role": "admin",
}
A vírgula depois de "admin" é inválida. JSON não permite vírgulas finais, ao contrário de objetos JavaScript ou dicts Python.
Correção: remova a vírgula final.
Origem: mais frequentemente vem de humanos editando JSON à mão, ou de ferramentas que exportam literais de objeto estilo JavaScript e os chamam de JSON.
Armadilha: o parser geralmente aponta para a linha depois da vírgula, não para a vírgula em si. Se o erro diz “linha 5”, olhe a linha 4 primeiro.
2. “Unexpected end of JSON input”
O que geralmente significa: o arquivo está truncado. Um colchete ou chave de fechamento está faltando.
{
"users": [
{ "name": "Alice" },
{ "name": "Bob" }
]
← chave de fechamento faltando para o objeto externo
Correção: conte seus colchetes. A maioria dos editores mostra correspondência de colchetes — ponha o cursor na { de abertura e veja com que ela casa.
Origem: downloads HTTP com falha (conexão caiu antes da resposta completa chegar), escritas incompletas de um processo com crash, corrupção de arquivo.
Diagnóstico: verifique o tamanho do arquivo. Se você esperava 200 KB e recebeu 180 KB, o arquivo está truncado — volte à origem.
3. “Unexpected token } in JSON”
O que geralmente significa: uma chave de fechamento a mais, ou uma vírgula faltando antes de uma chave irmã.
{
"name": "Alice" ← vírgula faltando aqui
"role": "admin"
}
Correção: adicione a vírgula faltante.
Ou o oposto:
{ "name": "Alice" } } ← chave de fechamento extra
Correção: remova a chave extra.
4. “Unexpected token u in JSON”
O que geralmente significa: literalmente o caractere u apareceu onde um valor era esperado. Na maioria das vezes, é a string undefined, que não é JSON válido.
{ "role": undefined }
undefined é um valor JavaScript, não um valor JSON. JSON só conhece null.
Correção: substitua undefined por null, ou omita a chave inteiramente.
Origem: código que faz JSON.stringify() num objeto com valores undefined — exceto que o stringify lida com isso corretamente na verdade. O erro é mais provavelmente de edição manual ou de um serializador não padrão.
5. “Unexpected token < in JSON”
O que geralmente significa: seu “JSON” é na verdade HTML. O < é o início de uma tag.
<!DOCTYPE html>
<html>
<head><title>500 Server Error</title>
...
Correção: verifique o que seu servidor está realmente retornando. Provavelmente é uma página de erro HTML em vez da resposta JSON que você esperava.
Origem: endpoint mal configurado, falha de autenticação redirecionando para uma página de login, servidor retornando página de erro em vez de corpo de erro JSON.
Diagnóstico: console.log(response.text) antes do parse. Se você ver HTML, o problema está no servidor, não no parse.
6. “Unexpected token ’ in JSON”
O que geralmente significa: aspas simples em vez de duplas.
{ 'name': 'Alice' }
Strings JSON devem usar aspas duplas. Aspas simples são JSON inválido, mesmo que funcionem em JavaScript e Python.
Correção: substitua todas as aspas simples por aspas duplas. Se as strings contêm aspas duplas literais, escape-as com \".
Origem: colar literais de objeto JavaScript e chamar de JSON; saída de dict Python que não passou por json.dumps().
7. “Unexpected token n in JSON”
O que geralmente significa: um NaN ou null solto escrito onde um número era esperado — ou, mais sutilmente, uma quebra de linha literal dentro de uma string.
{ "description": "hello
world" }
Strings JSON não podem conter quebras de linha literais. Precisam ser escapadas como \n.
Correção:
{ "description": "hello\nworld" }
Origem: construção manual de JSON a partir de entrada de várias linhas, ou sistemas que despejam campos de texto direto sem escape.
8. “Unexpected number in JSON”
O que geralmente significa: um número em formato inválido.
Números inválidos comuns:
+5(sinal de mais inicial — não permitido)07(zero inicial em inteiro — não permitido)1.(ponto decimal sem dígito depois).5(ponto inicial sem zero)Infinity,-Infinity,NaN(não permitidos)
Correção:
- Remova o
+inicial:+5→5 - Descarte zeros iniciais:
07→7 - Adicione o zero que falta:
1.→1.0,.5→0.5 - Substitua
Infinity/NaNpornullou uma string sentinela
Origem: serializar matemática de ponto flutuante que produziu Infinity, exportar dados numéricos de sistemas com convenções diferentes.
9. “Duplicate key ’…’ in JSON”
O que geralmente significa: um objeto tem a mesma chave duas vezes.
{
"name": "Alice",
"name": "Bob"
}
Parsers padrão tecnicamente aceitam isso — silenciosamente pegam o último valor. Parsers estritos rejeitam. Se o seu parser sinaliza duplicatas como erros, está te fazendo um favor.
Correção: decida qual valor é correto e remova o outro. Sempre.
Origem: fusões de dados que não deduplicaram adequadamente, edições manuais que reintroduziram uma chave sem remover a antiga.
10. “Expected ’:’ after property name in JSON”
O que geralmente significa: você usou = em vez de :, ou esqueceu os dois-pontos completamente.
{ "name" = "Alice" } ← errado (= em vez de :)
{ "name" "Alice" } ← errado (sem dois-pontos)
Correção: use dois-pontos.
Origem: memória muscular de outras linguagens (por exemplo, = em YAML ou TOML).
11. UTF-8 inválido ou BOM
O que geralmente significa: o arquivo começa com um BOM (byte-order mark) ou contém bytes UTF-8 inválidos.
O BOM (U+FEFF) é um marcador legado de codificação de arquivo do Windows. Parsers JSON tecnicamente deveriam rejeitá-lo, embora muitos tolerem silenciosamente.
Correção: remova o BOM. No macOS/Linux: tail -c +4 file.json > file-clean.json. No Windows: salve como “UTF-8 sem BOM” no seu editor.
Origem: Bloco de Notas do Windows salvando arquivos JSON, produtos Microsoft exportando texto, exportações mais antigas de CMS.
12. Erros “Circular structure” do JSON.stringify
Este é um erro de serialização, não de parse — mas aparece com frequência suficiente para mencionar.
const obj = { a: 1 }
obj.self = obj
JSON.stringify(obj) // TypeError: Converting circular structure to JSON
Correção: não passe uma estrutura auto-referenciada para stringify. Achate os dados antes de serializar, ou use uma biblioteca como flatted ou safe-stringify que lida com ciclos explicitamente.
Origem: componentes React, nós do DOM, modelos de ORM com referências circulares.
Um fluxo de depuração
Quando você bate num erro de parse JSON, aqui está o caminho mais rápido:
- Copie o JSON ofensor para um formatador
- Clique em Formatar — se rejeitar, ele vai dizer onde
- Olhe 2-3 linhas acima da linha reportada; o erro real frequentemente está antes
- Passe os olhos pelos suspeitos habituais — vírgula final, vírgula faltando, aspas simples, string não fechada
- Se o JSON for enorme, use busca binária: delete a segunda metade do documento e tente de novo. Se validar, o erro está na metade deletada. Vá afunilando.
- Verifique a origem — sua API realmente retornou JSON, ou HTML / texto puro?
Prevenção: hábitos que evitam erros antes que aconteçam
Valide JSON antes de commitar arquivos de configuração em controle de versão. Um hook de pré-commit que roda jq empty file.json pega a maioria dos problemas.
Use um linter (ESLint, Prettier, etc.) que entenda JSON e sinalize problemas ao salvar.
Prefira bibliotecas de serialização (JSON.stringify, json.dumps) em vez de construir strings JSON manualmente. Construção manual é de onde vêm vírgulas finais, chaves sem aspas e strings não escapadas.
Use JSON schema para documentos importantes, para que problemas de estrutura — não só de sintaxe — sejam pegos antes do deploy.
Mantenha valores tipados consistentes. Não alterne entre "1" (string) e 1 (número) para o mesmo campo em registros diferentes; alguém vai bater em erro de parse mais adiante.
A maioria dos erros desta lista é encontrável em segundos com nosso Formatador JSON. Cole o JSON quebrado, clique em Formatar, leia a mensagem de erro. Tudo roda no seu navegador para que você possa depurar configurações sensíveis ou respostas de API sem que nada saia do seu dispositivo. Uma passada de dois minutos por um formatador geralmente resolve o que estiver errado e coloca você de volta ao que importa.