Resolvendo "Unexpected token in JSON" e erros comuns de análise de JSON: Um Guia Completo

O JSON (JavaScript Object Notation) é a espinha dorsal da comunicação web moderna. Esteja você construindo uma API REST, configurando um servidor ou armazenando o estado de um aplicativo, o JSON está em toda parte. No entanto, sua sintaxe rigorosa frequentemente leva a erros frustrantes como SyntaxError: Unexpected token, JSON.parse: unexpected character ou simplesmente invalid JSON format.

Neste guia, vamos detalhar os erros de análise JSON mais comuns, explicar por que eles acontecem e mostrar exatamente como corrigi-los.

1. Mensagens de Erro JSON Comuns

Quando um analisador (como JSON.parse() no JavaScript) encontra um JSON inválido, ele lança um erro. Dependendo do ambiente, você pode ver:

• Navegador (Chrome/V8): SyntaxError: Unexpected token ' in JSON at position 0
• Firefox: SyntaxError: JSON.parse: unexpected character at line 1 column 1 of the JSON data
• Node.js: SyntaxError: Unexpected token ... in JSON at position ...
• Python: json.decoder.JSONDecodeError: Expecting property name enclosed in double quotes

A informação chave geralmente é o caractere que ele não esperava e a posição (ou linha/coluna) onde ocorreu.

---

2. Principais Causas e Soluções

2.1 Aspas Simples em vez de Aspas Duplas

O JSON exige estritamente aspas duplas (") para chaves e valores de string. Aspas simples (') são válidas em objetos JavaScript, mas inválidas em strings JSON.

O Erro (single quotes in JSON):

{
  'name': 'Tool3M'
}

A Solução: Substitua todas as aspas simples por aspas duplas.

{
  "name": "Tool3M"
}

2.2 Vírgulas Extras (Trailing Commas)

Ao contrário do JavaScript moderno, o JSON não permite uma vírgula após o último item em um objeto ou array.

O Erro (trailing comma in JSON):

{
  "id": 1,
  "status": "active",
}

A Solução: Remova a vírgula após a última propriedade.

{
  "id": 1,
  "status": "active"
}

2.3 Chaves sem Aspas

No JSON, as chaves devem ser sempre strings entre aspas duplas.

O Erro:

{
  id: 123
}

A Solução: Envolva as chaves em aspas duplas.

{
  "id": 123
}

2.4 Comentários no JSON

O padrão JSON não suporta comentários (// ou /* */) (comments in JSON). Embora algumas ferramentas (como o VS Code para tsconfig.json) os permitam, o JSON.parse() padrão falhará.

O Erro:

{
  "id": 1 // Isto é um comentário
}

A Solução: Remova todos os comentários antes da análise. Se precisar de metadados, use uma propriedade como "__comment": "texto".

2.5 Valores Especiais: NaN, Infinity e Undefined

O JSON não suporta NaN, Infinity, -Infinity ou undefined. Estes são valores específicos do JavaScript.

O Erro (NaN in JSON, Infinity in JSON):

{
  "value": NaN,
  "expired": undefined
}

A Solução: Use null ou uma string/número de preenchimento em seu lugar.

{
  "value": null,
  "expired": null
}

2.6 Caracteres de Controle e Quebras de Linha

Strings no JSON não podem conter caracteres de controle puros (como tabulações ou quebras de linha reais), a menos que sejam escapados.

O Erro:

{
  "description": "Esta é uma 
string de várias linhas"
}

A Solução: Use \n para quebras de linha e \t para tabulações.

{
  "description": "Esta é uma \nstring de várias linhas"
}

---

3. Solução de Problemas Avançada

3.1 BOM (Byte Order Mark)

Às vezes, um arquivo parece perfeito, mas ainda lança um SyntaxError na posição 0. Isso geralmente é causado por um caractere UTF-8 BOM oculto no início do arquivo. Solução: Salve o arquivo novamente como "UTF-8 sem BOM".

3.2 Caracteres Escapados Incorretamente

Se sua string contiver uma barra invertida (\) ou aspas duplas ("), elas devem ser escapadas.

• Correto: "path": "C:\\Windows\\System32"
• Correto: "quote": "Ele disse \"Olá\""

---

4. Medidas de Prevenção

1. Use um Linter: Use ferramentas como ESLint com o jsonc-parser ou a validação JSON integrada do VS Code.
2. Formatação Automática: Sempre passe seu JSON por um formatador antes de salvá-lo em um arquivo de configuração.
3. Validação de Esquema: Use JSON Schema para definir a estrutura de seus dados e validá-los programaticamente.
4. Try-Catch: Ao analisar dados dinâmicos, sempre envolva JSON.parse() em um bloco try...catch para lidar com erros graciosamente.

try {
  const data = JSON.parse(userInput);
} catch (e) {
  console.error("Falha ao analisar JSON:", e.message);
  // Mostre um erro amigável ao usuário
}

---

5. FAQ: Perguntas Frequentes

P: Por que estou recebendo "Unexpected token < in JSON at position 0"?

R: Isso quase sempre significa que seu código esperava JSON, mas recebeu HTML. Isso geralmente acontece quando uma chamada de API falha e o servidor retorna uma página de erro HTML (como uma página 404 ou 500) em vez da resposta JSON esperada.

P: Posso usar números hexadecimais no JSON?

R: Não. O JSON suporta apenas números decimais padrão. 0xFF causará um erro de análise (JSON parse error). Use 255 em seu lugar.

P: Como lidar com arquivos JSON grandes que travam meu analisador?

R: Para arquivos muito grandes, use um analisador de "streaming" como JSONStream (Node.js) ou ijson (Python), que processa o arquivo pedaço por pedaço em vez de carregar tudo na memória.

---

6. Ferramenta de Verificação Rápida

Se você está lutando para encontrar aquela vírgula que falta ou aspas mal colocadas, use nosso Formatador e Validador JSON. Ele irá:

• Destacar instantaneamente erros de sintaxe.
• Corrigir problemas comuns como aspas simples ou vírgulas extras.
• Formatar seu JSON para torná-lo legível por humanos.

---

Erros Relacionados

• Resolvendo erros de 'invalid base64 string'
• Como corrigir 'malformed URL' no JavaScript
• Entendendo erros de indentação YAML