Para corrigir um JSON inválido, cole-o em um validador de JSON, vá até a linha indicada e olhe o caractere logo antes do ponto apontado. Em nove de cada dez casos, o culpado é uma vírgula final, aspas simples, uma chave sem aspas, um comentário ou um colchete faltando. Se o erro diz Unexpected token < na posição 0, o problema não é o seu JSON: você recebeu uma página HTML. Este guia percorre cada erro comum de JSON, o que a mensagem realmente significa e como corrigir exatamente.
Por que o JSON é tão rígido
JSON (JavaScript Object Notation) parece JavaScript, mas sua gramática é bem menor e mais rígida. O padrão, RFC 8259, permite apenas alguns blocos: objetos em { }, arrays em [ ], strings entre aspas duplas, números, true, false e null. Qualquer outra coisa, inclusive sintaxes que JavaScript ou Python aceitam sem reclamar, invalida o documento inteiro.
Essa rigidez é uma vantagem. Como todos os parsers concordam com o mesmo pequeno conjunto de regras, um JSON escrito em uma linguagem pode ser lido com segurança em qualquer outra. A desvantagem é que um único caractere fora do lugar quebra tudo, e os parsers costumam parar no primeiro problema que encontram.
Como corrigir um JSON inválido passo a passo
- Copie o texto exato. Use a entrada original, não uma versão que você já arrumou. Se veio de uma API, copie o corpo da resposta exatamente como chegou.
- Cole no validador. Abra o validador e formatador de JSON, cole o texto e envie.
- Encontre a posição indicada. Anote a linha, a coluna ou a posição da mensagem de erro.
- Olhe um pouco à esquerda. A posição indicada é onde o parser desistiu, o que costuma ser um ou dois caracteres depois do erro real. Uma vírgula final, por exemplo, normalmente é apontada no colchete de fechamento que vem depois dela.
- Corrija um erro e valide de novo. Os parsers só informam o primeiro problema, então repita até a entrada passar.
- Formate o resultado. Quando estiver válido, a versão formatada e indentada facilita muito confirmar que a estrutura é a esperada.
Os 10 erros de JSON mais comuns e como corrigi-los
1. Vírgulas finais
Uma vírgula depois do último item de um objeto ou array é o erro de JSON mais comum, porque o código JavaScript permite isso e muitos editores a deixam para trás.
{"name": "Ada", "role": "admin",} // inválido
{"name": "Ada", "role": "admin"} // válidoCorreção: apague a vírgula antes do } ou ] de fechamento.
2. Aspas simples
Strings e chaves de JSON precisam usar aspas duplas. Aspas simples funcionam em JavaScript e Python, mas não em JSON.
{'name': 'Ada'} // inválido
{"name": "Ada"} // válidoCorreção: troque as aspas simples em volta de chaves e valores por aspas duplas. Cuidado com apóstrofos dentro do texto, como em "it's", que estão corretos e devem ficar.
3. Chaves sem aspas
Todo nome de propriedade precisa ser uma string entre aspas.
{name: "Ada"} // inválido
{"name": "Ada"} // válido4. Vírgulas faltando
Quando dois valores ficam lado a lado sem vírgula, o parser reclama do segundo. Isso costuma acontecer depois de editar um arquivo à mão ou juntar dois trechos.
{"a": 1 "b": 2} // inválido
{"a": 1, "b": 2} // válidoCorreção: adicione a vírgula logo depois do valor anterior, pouco antes da posição que o erro aponta.
5. Comentários
O JSON padrão não tem comentários. Tanto // ... quanto /* ... */ são inválidos. Algumas ferramentas usam formatos mais flexíveis (JSONC ou JSON5) para arquivos de configuração, que permitem comentários e vírgulas finais, mas um parser de JSON estrito vai rejeitá-los.
Correção: remova os comentários, ou guarde as anotações em um campo comum como "_comment": "..." se o programa que recebe o arquivo ignora chaves desconhecidas.
6. Valores de Python ou JavaScript
O JSON só conhece true, false e null em minúsculas. True, False e None do Python são inválidos, assim como undefined, NaN e Infinity do JavaScript.
Correção: converta-os para os equivalentes em JSON e transforme valores como NaN em null ou em uma string. Se você imprime um dicionário Python, use json.dumps() em vez de print() ou str(), que geram sintaxe Python, não JSON.
7. Aspas curvas de documentos e apps de conversa
Texto copiado de um editor de texto, de uma apresentação ou de um app de mensagens costuma trazer aspas curvas (“ ”) em vez de retas ("). Elas parecem quase iguais, mas são caracteres diferentes.
Correção: troque as aspas curvas em volta de chaves e valores por aspas duplas retas, e copie código de fontes em texto simples sempre que possível.
8. Escapes errados e quebras de linha dentro de strings
Uma barra invertida inicia uma sequência de escape, então um caminho do Windows como "C:\new\file" quebra ou muda de sentido sem aviso. Uma quebra de linha real dentro de uma string também é inválida.
{"path": "C:\new\file"} // inválido
{"path": "C:\\new\\file"} // válido
{"note": "line one\nline two"} // válido: a quebra de linha está escapadaCorreção: duplique cada barra invertida literal e escreva as quebras de linha como \n.
9. Colchetes faltando ou sobrando
Um erro como Unexpected end of JSON input geralmente significa que falta um } ou ] de fechamento, ou que o texto foi cortado no meio. Um colchete a mais produz um erro de token inesperado perto do final.
Correção: formate as partes que são analisadas, ou indente o texto à mão, e conte os colchetes de abertura e fechamento nível por nível. Se a entrada foi truncada (por exemplo, uma linha de log com limite de tamanho), obtenha o original completo em vez de adivinhar o final.
10. Vários documentos JSON grudados
Um documento JSON contém exatamente um valor de nível superior. Dois objetos seguidos, como {"id":1}{"id":2}, não são válidos como um único documento, e um arquivo de log delimitado por linhas, em que cada linha é um objeto, também não.
Correção: envolva os itens em um array, [{"id":1},{"id":2}], ou analise o arquivo linha por linha se ele foi feito para ser delimitado por linhas.
Entendendo as mensagens de erro
Cada linguagem e navegador descreve o mesmo problema de um jeito. Veja como traduzir as mensagens que você mais vai encontrar.
Unexpected token < in JSON at position 0
O primeiro caractere é <, o que significa que o texto é HTML, não JSON. Um servidor devolveu uma página de erro, de login ou um 404 em vez de dados. Verifique o código de status HTTP e o cabeçalho Content-Type antes de analisar. Nossa consulta de cabeçalhos HTTP mostra os dois para qualquer URL pública, e o verificador de redirecionamento de URL revela se a requisição está sendo redirecionada para outro lugar, como uma página de login.
Unexpected token u in JSON at position 0
O valor passado ao parser era undefined, que vira o texto undefined. O bug está antes no seu código: a variável nunca foi definida.
Unexpected end of JSON input
O parser chegou ao fim antes de a estrutura estar completa. Procure um colchete faltando ou um corpo de resposta vazio.
Expected property name or '}' / Expecting property name enclosed in double quotes
A primeira mensagem vem do JavaScript e a segunda do módulo json do Python. As duas costumam apontar para uma vírgula final, uma chave com aspas simples ou uma chave sem aspas.
Um caractere invisível na posição 0
Se o texto parece perfeito mas falha logo no primeiro caractere, ele pode começar com uma marca de ordem de bytes (BOM) ou outro caractere invisível. Salve o arquivo como UTF-8 sem BOM ou remova esse primeiro caractere antes de analisar.
Exemplo prático: corrigindo um trecho de configuração quebrado
Este é um trecho que alguém colou de uma mensagem de chat:
{
name: 'My App',
"debug": True,
// turn this off in production
"plugins": ["seo", "cache",],
"path": "C:\apps\myapp"
}O validador para no primeiro erro, a chave sem aspas da linha 2. Corrigindo um de cada vez:
- Linha 2: coloque a chave entre aspas e use aspas duplas, ficando
"name": "My App". - Linha 3: troque
Trueportrue. - Linha 4: apague o comentário.
- Linha 5: remova a vírgula depois de
"cache". - Linha 6: duplique as barras invertidas, ficando
"C:\\apps\\myapp".
O resultado válido:
{
"name": "My App",
"debug": true,
"plugins": ["seo", "cache"],
"path": "C:\\apps\\myapp"
}Validando JSON pela linha de comando
Para arquivos grandes ou verificações automáticas, valide localmente. Cada um destes comandos termina com erro se a entrada for inválida, então você pode usá-los em scripts:
python3 -m json.tool data.jsonimprime o JSON formatado, ou um erro com a linha e a coluna.jq empty data.jsonverifica o arquivo e não imprime nada se ele for válido (é preciso ter o jq instalado).node -e "JSON.parse(require('fs').readFileSync('data.json','utf8'))"usa o mesmo parser dos apps Node.js.
Armadilhas a evitar
- Não corrija o sintoma com localizar e substituir. Trocar todas as aspas simples às cegas também quebra os apóstrofos dentro do texto. Corrija só as aspas em volta de chaves e valores.
- Não esconda erros de análise. Código que devolve um objeto vazio sempre que a análise falha esconde bugs reais. Registre o erro e os primeiros caracteres da entrada (sem registrar dados privados).
- Corrija a origem, não só a saída. Se um sistema vive gerando JSON quebrado, monte-o com um serializador adequado como
JSON.stringify()oujson.dumps()em vez de concatenar strings. - Fique atento a dados escondidos em outras codificações. JSON dentro de uma URL ou token costuma chegar codificado. Decodifique primeiro com o decodificador de URL ou o decodificador Base64 e depois valide.
Ferramentas e guias relacionados
- O validador e formatador de JSON verifica a sintaxe e formata o JSON para ficar legível.
- O analisador de URL divide o endereço de uma API em partes para você confirmar que está chamando o endpoint certo.
- O conversor de entidades HTML decodifica textos como
", que às vezes aparecem quando o JSON foi incorporado em HTML. - Como verificar registros DNS ajuda quando uma API devolve HTML porque o domínio aponta para o servidor errado.
- Como remover duplicados e limpar listas é útil para organizar valores antes de colocá-los em um array JSON.
Perguntas frequentes
Por que meu JSON é inválido se parece estar certo?
Os suspeitos de sempre são caracteres invisíveis ou parecidos: uma vírgula final, aspas curvas em vez de retas, uma marca de ordem de bytes no início do arquivo ou um comentário. Um validador aponta o local exato para você não ter que procurar a olho.
Vírgulas finais são permitidas em JSON?
Não. O JSON padrão não permite vírgula depois do último item de um objeto ou array. Formatos flexíveis como JSONC e JSON5 permitem, mas parsers estritos como o JSON.parse as rejeitam.
JSON pode ter comentários?
Não. O JSON padrão não tem sintaxe de comentários. Remova-os antes de analisar, ou use um campo comum como _comment se o programa que lê o arquivo ignora chaves extras.
O que significa Unexpected token < in JSON at position 0?
O texto começa com um sinal de menor que, então quase certamente é uma página HTML, como uma página de erro, de login ou um 404, em vez de JSON. Verifique o código de status HTTP, o cabeçalho Content-Type e a URL solicitada.
JSON diferencia maiúsculas de minúsculas?
Sim. Os literais devem ser true, false e null em minúsculas, e as chaves diferenciam maiúsculas, então Name e name são duas chaves diferentes.
Qual a diferença entre validar e formatar JSON?
Validar verifica se o texto segue as regras do JSON e informa o primeiro erro. Formatar adiciona quebras de linha e indentação a um JSON válido para facilitar a leitura. Não altera os dados.
