JSON inválido? Os 7 erros por trás de quase toda falha

“Unexpected token” e “Unexpected end of JSON input” estão entre os erros que desenvolvedores mais veem. JSON é um formato rigoroso, bem mais que o JavaScript de onde veio, e quase toda falha se resume a um de poucos erros.

1. Vírgula no final

Uma vírgula depois do último item de um objeto ou array é o erro número um. O JavaScript aceita; o padrão JSON, não.

{"name": "Ana", "age": 31,}   ✗
{"name": "Ana", "age": 31}    ✓

2. Aspas simples e 3. chaves sem aspas

Toda chave e toda string precisam de aspas duplas. {name: 'Ana'} é JavaScript válido, mas JSON inválido; o certo é {"name": "Ana"}.

4. Comentários

JSON não tem comentários. // e /* */ são erros, o que surpreende quem copia de um arquivo de configuração em JSON5 ou JSONC, como as configurações do VS Code.

5. Valores especiais e 6. caracteres sem escape

undefined, NaN, Infinity e funções não existem em JSON; use null ou um número. Dentro de uma string, aspas duplas se escrevem \" e a barra invertida \\, e uma quebra de linha \n. Caminhos do Windows são uma armadilha clássica: "C:\new" contém uma quebra de linha, não uma barra seguida de n.

7. Chaves ou colchetes faltando ou sobrando

Um } ou ] de fechamento faltando costuma aparecer como erro no fim do texto, longe do problema real. Formatar o JSON com indentação mostra na hora qual nível está quebrado.

Erros difíceis de ver

Alguns JSON inválidos parecem perfeitos na tela:

• Aspas curvas. Texto copiado de um editor de texto, de um app de chat ou de uma apresentação muitas vezes traz “ e ” no lugar de aspas duplas retas. Elas parecem quase iguais, mas o JSON aceita apenas o caractere " reto.
• Uma marca de ordem de bytes (BOM). Alguns editores do Windows salvam arquivos com um caractere invisível no início. O JSON.parse do JavaScript e o json.loads do Python o rejeitam, e o erro aponta para a posição 0.
• Espaços não separáveis e outros caracteres invisíveis colados de páginas da web.

JSON válido que ainda causa bugs

O json.dumps do Python escreve NaN e Infinity por padrão, e outros parsers os rejeitam; use allow_nan=False para pegar isso cedo. Inteiros muito grandes, como IDs de 64 bits de banco de dados, são JSON válido mas perdem precisão no JavaScript acima de 9007199254740991, por isso muitas APIs os enviam como strings. A maioria dos parsers aceita chaves duplicadas, mas o último valor vence sem aviso.

Como ler a mensagem de erro

Os parsers informam onde desistiram, não onde você errou. Uma vírgula faltando costuma ser apontada no início da chave seguinte, e um colchete de fechamento faltando, no fim da entrada. Olhe logo antes da posição indicada.

{
  "name": "Ana"
  "age": 31        ← o erro é apontado aqui (linha 3)
}                   a vírgula que falta está no fim da linha 2

Ache o ponto exato

O validador de JSON da 4Dev confere o seu texto pelo padrão JSON (RFC 8259) e mostra a linha e a coluna do primeiro erro, com uma sugestão de correção. Ele verifica a sintaxe, não o significado: um JSON válido ainda pode ter um tipo errado ou um campo faltando para a sua aplicação.

Abrir o validador de JSON