Erros comuns de JSON e como corrigir cada um
Quase todo JSON recusado cai em um punhado de erros de sintaxe. Veja cada um com o exemplo inválido, a mensagem que o parser mostra e a correção, e como achar o ponto exato no seu texto.
Por que o JSON é tão rígido
JSON é um formato de sintaxe pequena e fechada, definido na RFC 8259 e no padrão ECMA-404. Ele não aceita comentários, vírgula no fim, aspas simples nem valores como NaN. Muita gente chega ao JSON vindo de código JavaScript, de arquivos de configuração ou de uma planilha, e leva hábitos que lá funcionam. Aqui o parser para no primeiro problema e devolve uma mensagem curta, que muda de um navegador ou ferramenta para outro.
Os exemplos abaixo foram executados de verdade em dois lugares: o verificador de JSON do Me Ajuda Flow (que informa linha e coluna) e o JSON.parse do Node.js 24, que usa o mesmo motor V8 do Chrome. Outros navegadores, como Firefox e Safari, escrevem mensagens diferentes para o mesmo erro, então use o texto como pista e a posição como guia.
1. Vírgula sobrando no fim
É o erro número um, e acontece quando você apaga o último item de uma lista e deixa a vírgula do anterior.
{"a":1,"b":2,}
- Verificador do site: "Vírgula sobrando antes de }" (linha 1, coluna 14).
- Node.js 24:
Expected double-quoted property name in JSON at position 13 (line 1 column 14).
Em listas a mensagem do Node.js é diferente: para [1,2,3,] ele diz Unexpected token ']', e o site diz "Vírgula sobrando antes de ]" na coluna 8. A gramática da RFC 8259 só permite vírgula entre itens, nunca depois do último. Conserto: apague a vírgula final: {"a":1,"b":2}.
2. Faltou vírgula entre itens
O inverso do anterior. Muito comum ao colar um item novo no meio de um objeto.
{"a":1 "b":2}
O site responde "Esperava ',' ou '}' (faltou uma vírgula?)" na coluna 8, e o Node.js responde Expected ',' or '}' after property value in JSON at position 7. O ponto apontado é logo depois do valor que ficou sem vírgula. Conserto: {"a":1,"b":2}.
3. Aspas simples
Em JSON, texto e nomes de chave usam aspas duplas (o caractere U+0022 na gramática da RFC). Aspas simples são válidas em JavaScript e Python, mas não em JSON.
{'nome':'Ana'}
- Site: "Aspas simples não são permitidas; use aspas duplas" (linha 1, coluna 2).
- Node.js 24:
Expected property name or '}' in JSON at position 1.
Conserto: {"nome":"Ana"}. Se o JSON saiu de um print de dicionário em Python, ele também traz True, False e None, que precisam virar true, false e null (a RFC exige as palavras em minúsculas). Teste real: {"ok":True} dá "Valor inesperado "True" (faltaram aspas em um texto?)" no site e Unexpected token 'T' no Node.js.
4. Nome de chave sem aspas
Em um literal de objeto JavaScript, {nome: "Ana"} é normal. Em JSON, toda chave é um texto e precisa de aspas duplas.
{nome:"Ana"}
O site diz "Esperava o nome de uma chave entre aspas duplas" (coluna 2) e o Node.js, a mesma mensagem do caso das aspas simples: Expected property name or '}'. A mensagem não distingue os dois casos, então olhe o caractere na posição indicada. Conserto: {"nome":"Ana"}.
5. Comentários
Nem a RFC 8259 nem o ECMA-404 definem comentários. A RFC admite que um parser pode aceitar extensões fora do padrão, mas você não pode contar com isso. Arquivos de configuração que aceitam comentários (o chamado JSONC, usado por algumas ferramentas) são outro formato.
{
// total
"a": 1
}
O site diz "Comentários não fazem parte do JSON" (linha 2, coluna 3) e o Node.js, Expected property name or '}' na mesma posição. Se o comentário vem depois de um valor, como em {"a":1 // x, a mensagem vira "Esperava ',' ou '}'", porque o parser não chega a reconhecer a barra como comentário. Conserto: apague o comentário. Se você precisa de uma anotação, guarde-a em um campo normal, por exemplo "observacao": "total".
6. Número com zero à esquerda, ponto solto ou sinal de mais
A gramática de números da RFC 8259 (seção 6) diz que zeros à esquerda não são permitidos. CEP, código de produto e telefone costumam cair aqui, porque parecem números mas são identificadores.
{"cep":01310}
O site responde "Número inválido (zero à esquerda, ponto sem dígitos ou texto colado ao número)" (coluna 8) e o Node.js, Unexpected number in JSON at position 8. Outros números inválidos pela mesma gramática, testados da mesma forma:
{"v":5.}(ponto sem dígitos depois): o Node.js dizUnterminated fractional number.{"v":+5}(sinal de mais):Unexpected token '+'.{"v":0x1F}(hexadecimal): o parser lê o0e reclama dox.
Conserto: se é um identificador, coloque entre aspas: {"cep":"01310"}. Isso preserva o zero. Se é uma quantidade, escreva sem o zero extra (1310), sem + e com dígitos nos dois lados do ponto. Lembre também que o separador decimal é o ponto, nunca a vírgula.
7. Quebra de linha ou tabulação dentro de um texto
A RFC 8259 (seção 7) exige que os caracteres de controle, de U+0000 a U+001F, sejam escapados dentro de textos. Isso inclui a quebra de linha e a tabulação. Um valor digitado em duas linhas, ou colado de uma célula do Excel com Alt+Enter, quebra o JSON.
{"t":"linha1
linha2"}
- Site: "Quebra de linha ou caractere de controle dentro de uma string (use \n)" (linha 1, coluna 13).
- Node.js 24:
Bad control character in string literal in JSON at position 12. O mesmo vale para uma tabulação real dentro do texto.
Conserto: troque a quebra real pela sequência \n (barra invertida e a letra n): {"t":"linha1\nlinha2"}. Quem gera o JSON por concatenação de texto deve usar uma função de serialização (como JSON.stringify), que escapa tudo sozinha. Atenção com a barra invertida em caminhos: "C:\\temp" é válido, mas escrito com uma barra só, \t é lido como tabulação.
8. BOM no início do arquivo
O BOM (U+FEFF) é um marcador invisível que alguns editores gravam no começo de arquivos UTF-8. A RFC 8259 (seção 8.1) diz que implementações não devem adicioná-lo a um JSON enviado por rede, e que o parser pode ignorá-lo em vez de tratá-lo como erro. Ou seja, o comportamento varia.
U+FEFF{"a":1}
Teste real: o verificador do Me Ajuda Flow ignora o BOM e aceita o texto. O JSON.parse do Node.js 24 recusa: Unexpected token '', "{"a":1}" is not valid JSON, com o caractere invisível aparecendo entre aspas. Esse é o caso mais confuso, porque o JSON parece perfeito. Conserto: salve o arquivo como "UTF-8" sem BOM, ou remova o primeiro caractere se ele for U+FEFF antes de analisar.
9. NaN, Infinity e undefined
A RFC 8259 (seção 6) diz que valores numéricos que a gramática não representa, como Infinity e NaN, não são permitidos. As únicas palavras-valor são true, false e null, em minúsculas. O undefined do JavaScript também não existe.
{"v":NaN}
O site diz "NaN e Infinity não existem em JSON" e, para {"v":undefined}, "undefined não existe em JSON; use null". O Node.js responde Unexpected token 'N' e Unexpected token 'u'. Um detalhe útil de verificar: JSON.stringify({a:NaN,b:undefined,c:Infinity}) devolve {"a":null,"c":null}. Ou seja, o NaN e o Infinity viram null e o campo undefined simplesmente some. Por isso o erro costuma aparecer quando o texto foi montado à mão, e não por JSON.stringify. Conserto: use null para "sem valor" e trate o cálculo que gerou o NaN antes de serializar.
10. Conteúdo depois do fim, texto cortado e chaves repetidas
- Dois JSONs colados:
{"a":1}{"b":2}dá "Há conteúdo depois do fim do JSON" (coluna 8). Um texto JSON é um único valor. Para vários registros, envolva em uma lista:[{"a":1},{"b":2}]. - Texto cortado:
{"a":[1,2dá "O texto termina antes de fechar [" no site. O sinal é o parser chegar ao fim sem fechar colchetes ou chaves, comum em respostas truncadas ou copiadas pela metade. - Chave repetida:
{"a":1,"a":2}não é recusado nem pelo site nem peloJSON.parse. A RFC 8259 (seção 4) diz que os nomes devem ser únicos e que, se repetidos, o comportamento de quem recebe é imprevisível. O site mantém os dois e avisa, mas a maioria dos sistemas fica só com o último valor. Remova a duplicata.
Como achar o erro rápido
- Cole o texto inteiro no validador de JSON e leia linha e coluna. O erro real costuma estar nesse ponto ou logo antes dele.
- Comece pelas causas mais frequentes: vírgula sobrando, vírgula faltando, aspas simples.
- Se o texto parece perfeito e mesmo assim falha, suspeite de caractere invisível (BOM, aspas "inteligentes" coladas de um editor de texto, espaço sem quebra).
- Depois de corrigir, formate o resultado e confira se os números e textos continuam como você queria, especialmente CEPs e códigos com zero à esquerda.
Exemplo completo de correção
Este texto tem quatro problemas ao mesmo tempo: aspas simples, chave sem aspas, zero à esquerda e vírgula sobrando.
{'cliente':"Ana", ativo:true, "cep":01310, "tags":["a","b",],}
Corrigido, ele fica assim, e o validador do site o aceita sem erro:
{"cliente":"Ana","ativo":true,"cep":"01310","tags":["a","b"]}
Parsers mostram um erro por vez, então um texto assim exige várias tentativas. Corrija, valide de novo e repita até passar.
Padrão de referência
Para decidir o que é ou não JSON válido, as referências são a RFC 8259 e o ECMA-404. O ECMA-404 define apenas a sintaxe, sem dizer como mapear valores para uma linguagem de programação. Se uma ferramenta aceita mais do que isso (comentários, vírgula final), ela está usando uma extensão, e o arquivo pode ser recusado por outro sistema.
Para validar, formatar e achar o ponto do erro, use a ferramenta JSON do Me Ajuda Flow. Se o seu JSON vem de uma planilha, veja a conversão em CSV para JSON, e para trocar entre formatos de configuração, JSON e YAML.