Como corrigir erros de parse de JSON e Unexpected token

Se você já trabalhou com JSON, com certeza esbarrou na temida mensagem SyntaxError: Unexpected token. Ela aparece no console do navegador, em respostas de API, em arquivos de configuração e em pipelines de CI/CD. O erro em si não ajuda muito: ele avisa que algo está errado, mas raramente explica o quê.

Este guia percorre as causas mais comuns dos erros de parse de JSON, mostra exatamente como corrigir cada uma e oferece um fluxo de trabalho confiável para detectar esses problemas antes que causem dor de cabeça. Se quiser ir direto para a correção, cole o seu JSON quebrado no JSON Formatter e ele vai destacar a linha e o caractere exatos onde o erro acontece.

O que "Unexpected token" realmente significa?

Os parsers de JSON leem o texto caractere por caractere. Quando o parser encontra um caractere que não pertence ao formato segundo a especificação JSON, ele lança um SyntaxError. O "unexpected token" é simplesmente o caractere que o parser não esperava encontrar naquela posição.

Por exemplo, se o parser espera uma aspa dupla para iniciar o valor de uma string, mas encontra uma aspa simples, ele reporta algo como:

SyntaxError: Unexpected token ' in JSON at position 14

O número da posição indica quantos caracteres a partir do início da string o parser conseguiu ler antes de desistir. Isso é útil, mas contar caracteres manualmente em um arquivo JSON grande é cansativo. É aí que uma ferramenta como o JSON Formatter se torna indispensável: ela aponta visualmente o local do erro.

As 5 causas mais comuns de erros de parse de JSON

1. Vírgulas sobrando (trailing commas)

Esta talvez seja a causa mais frequente de erros de parse de JSON, especialmente para quem escreve JavaScript com frequência. Arrays e objetos em JavaScript aceitam tranquilamente vírgulas no final. JSON não.

A versão quebrada:

{
  "name": "Alice",
  "age": 30,
  "city": "Tokyo",
}

A versão corrigida:

{
  "name": "Alice",
  "age": 30,
  "city": "Tokyo"
}

A vírgula depois de "Tokyo" é o problema. O parser de JSON lê a vírgula, espera outro par chave-valor e, em vez disso, encontra uma chave de fechamento. Essa chave de fechamento vira o "unexpected token".

Vírgulas sobrando também aparecem em arrays:

{
  "colors": ["red", "green", "blue",]
}

Remova a vírgula depois de "blue" e o erro desaparece:

{
  "colors": ["red", "green", "blue"]
}

Esse engano é tão fácil de cometer que muitos editores de código hoje têm uma opção para remover automaticamente as vírgulas sobrando ao salvar arquivos JSON. Se o seu editor oferece esse recurso, ative-o.

2. Aspas simples em vez de aspas duplas

JSON exige aspas duplas para todas as strings e chaves. Aspas simples não são válidas, mesmo que JavaScript e Python aceitem ambas para literais de string.

A versão quebrada:

{
  'name': 'Alice',
  'age': 30
}

A versão corrigida:

{
  "name": "Alice",
  "age": 30
}

Esse erro costuma surgir quando alguém copia um dicionário Python ou um objeto literal de JavaScript e tenta usá-lo como JSON. Os dois formatos parecem semelhantes, mas não são intercambiáveis.

Um simples find-and-replace de ' por " geralmente resolve, mas tome cuidado se os valores das suas strings contiverem apóstrofos. Nesse caso, você precisa escapá-los ou tratar a substituição com mais atenção. Colar o texto no JSON Formatter vai sinalizar as posições exatas onde aparecem aspas simples, para que você possa corrigi-las uma a uma.

3. Chaves sem aspas

Em JavaScript, as chaves de um objeto não precisam de aspas se forem identificadores válidos. Em JSON, toda chave precisa ser uma string entre aspas duplas, sem exceções.

A versão quebrada:

{
  name: "Alice",
  age: 30
}

A versão corrigida:

{
  "name": "Alice",
  "age": 30
}

Isso costuma acontecer quando alguém escreve JSON à mão ou copia de um código-fonte JavaScript. Também aparece em arquivos de configuração quando a pessoa esquece que o JSON é mais rígido do que a linguagem que costuma usar.

4. Comentários no JSON

JSON não suporta comentários. Nem comentários de uma linha (//), nem comentários de várias linhas (/* */), nem comentários com cerquilha (#). Se o parser encontrar qualquer um deles, ele lança um erro.

A versão quebrada:

{
  // User's display name
  "name": "Alice",
  /* Age in years */
  "age": 30
}

A versão corrigida:

{
  "name": "Alice",
  "age": 30
}

Esse é um incômodo real. É perfeitamente razoável querer comentários em um arquivo de configuração, e muitos desenvolvedores ficam frustrados por o JSON não permitir isso. Algumas ferramentas (como o settings.json do VS Code) na verdade usam um superconjunto chamado JSONC (JSON with Comments), mas os parsers de JSON padrão rejeitam comentários sem dó.

Para uma comparação lado a lado de JSONC, JSON5, campos _comment e scripts de remoção, e qual escolher para arquivos de config, dados ou API, veja JSON pode ter comentários?. Se você prefere abandonar o JSON de vez, o YAML suporta comentários nativamente com o caractere #, e dá para converter entre os dois formatos com facilidade. Confira nosso artigo de dicas de formatação de JSON para saber mais sobre como lidar com arquivos JSON complexos.

5. Caracteres BOM (Byte Order Mark)

Esse é traiçoeiro porque você não consegue ver o problema apenas olhando o arquivo. Um BOM é um caractere invisível (U+FEFF) que alguns editores de texto, especialmente no Windows, inserem bem no início de um arquivo. Ele informa ao editor qual codificação o arquivo usa.

O parser de JSON esbarra nesse caractere invisível antes de chegar ao { ou [ de abertura, e não faz ideia do que fazer com ele. A mensagem de erro pode ser parecida com esta:

SyntaxError: Unexpected token  in JSON at position 0

Aquele espaço que parece em branco antes de "in JSON" é o caractere BOM.

Como corrigir:

• Abra o arquivo em um editor hexadecimal e remova os três primeiros bytes (EF BB BF para o BOM de UTF-8).
• No VS Code, clique no indicador de codificação na barra de status, escolha "Save with Encoding" e selecione "UTF-8" (sem BOM).
• Use uma ferramenta de linha de comando: sed -i '1s/^\xEF\xBB\xBF//' file.json

O estado antes (mostrado em hexadecimal):

EF BB BF 7B 0A 20 20 22 6E 61 6D 65 22 ...

O estado depois:

7B 0A 20 20 22 6E 61 6D 65 22 ...

O conteúdo do arquivo parece idêntico em um editor de texto, mas agora o parser consegue lê-lo.

Outras causas que vale a pena conhecer

Além das cinco principais, aqui vão mais alguns problemas que costumam pegar as pessoas de surpresa:

Colchetes ou chaves desbalanceados

Um } ou ] de fechamento faltando vai causar um erro de parse, geralmente reportado no fim do arquivo. Se o seu JSON tem muitos níveis aninhados, encontrar o colchete desbalanceado a olho nu é quase impossível. Um formatador com correspondência de colchetes vai economizar bastante tempo.

Caracteres de controle dentro de strings

Quebras de linha, tabulações e outros caracteres de controle dentro de strings JSON precisam ser escapados. Uma quebra de linha literal dentro do valor de uma string não é válida:

{"message": "Hello
World"}

Deveria ser:

{"message": "Hello\nWorld"}

Números com zeros à esquerda

Números em JSON não podem ter zeros à esquerda. 007 não é JSON válido: precisa ser 7, ou 0.07, ou algum outro formato numérico padrão.

{
  "code": 007
}

Corrigido:

{
  "code": 7
}

Usar undefined ou NaN

O undefined e o NaN do JavaScript não são valores JSON válidos. Se você serializar um objeto que contém undefined, a maioria dos serializadores vai omitir a chave ou lançar um erro. NaN e Infinity são rejeitados da mesma forma.

Um fluxo de trabalho confiável para depurar JSON

Quando você se depara com um erro de parse e o arquivo tem mais do que algumas linhas, ficar encarando o texto bruto não é produtivo. Aqui está um fluxo de trabalho que funciona de forma consistente:

1. Cole o JSON no JSON Formatter. Ele vai mostrar o local exato do erro com um número de linha e uma descrição do que deu errado.

2. Observe a posição reportada. O erro geralmente está na posição que o parser indica, ou logo antes dela. Às vezes o engano real está algumas linhas antes: por exemplo, uma vírgula faltando na linha 10 pode só causar erro quando o parser chega à linha 11.

3. Verifique as cinco causas principais listadas acima. Na prática, vírgulas sobrando e aspas simples respondem pela maioria dos erros de parse do mundo real.

4. Se o arquivo foi gerado por código, verifique a etapa de serialização. Você está usando JSON.stringify() ou uma função equivalente? Montar strings JSON à mão com concatenação de strings é uma fonte comum de bugs.

5. Se o arquivo foi baixado ou recebido de uma API, verifique a codificação. Problemas de BOM, divergências de codificação de caracteres e respostas truncadas geram erros de parse.

Erros de parse em diferentes ambientes

As mensagens de erro variam de plataforma para plataforma, o que pode tornar confusa a busca por soluções.

No navegador (Chrome, Firefox):

SyntaxError: Unexpected token < in JSON at position 0

Esse erro em particular, < inesperado na posição 0, quase sempre significa que o servidor retornou uma página de erro em HTML em vez de JSON. Verifique a aba de rede para ver o que a API realmente retornou.

No Node.js:

SyntaxError: Unexpected token } in JSON at position 142

O Node fornece um número de posição que você pode usar para localizar o problema.

No Python:

json.decoder.JSONDecodeError: Expecting property name enclosed in double quotes: line 3 column 5

O Python é bem prestativo: ele dá tanto o número da linha quanto o número da coluna.

No Java (Jackson):

com.fasterxml.jackson.core.JsonParseException: Unexpected character ('}' (code 125)): was expecting double-quote to start field name

O Jackson é verboso, mas específico sobre o que esperava encontrar em comparação com o que de fato encontrou.

Como evitar erros de parse desde o início

Em vez de corrigir os erros depois que acontecem, alguns hábitos podem eliminar a maior parte dos erros de parse de JSON:

• Use JSON.stringify() para produzir JSON, e não concatenação de strings. Isso vale para qualquer linguagem: use o serializador embutido.
• Configure seu editor para validar JSON ao salvar. VS Code, IntelliJ e Sublime Text têm validação de JSON embutida ou disponível como plugin.
• Adicione uma etapa de lint ao seu pipeline de CI. Uma checagem simples como python -m json.tool < config.json detecta arquivos malformados antes que cheguem à produção.
• Ao editar JSON à mão, use uma ferramenta com validação em tempo real. O JSON Formatter valida enquanto você digita e mostra os erros imediatamente.

Para mais sobre como escrever JSON limpo, veja nossas dicas de formatação de JSON e o guia de sintaxe de JSON. Se você encontrar erros de parse ao depurar respostas de API com curl, nosso guia para formatar a saída JSON do curl mostra como detectar respostas malformadas no terminal antes que cheguem ao seu código.

Quando o JSON não é o formato certo

Se você se vê brigando com as limitações do JSON com frequência, querendo comentários, precisando de strings de várias linhas ou lidando com configurações aninhadas complexas, pode valer a pena considerar o YAML como alternativa. O YAML suporta comentários, lida naturalmente com texto de várias linhas e costuma ser mais legível para arquivos de configuração.

O custo dessa escolha é que o YAML é sensível à indentação e tem suas próprias armadilhas (coerção implícita de tipos, por exemplo). Mas, para arquivos de configuração em que pessoas precisam ler e editar o conteúdo, o YAML costuma ser a opção mais prática. Você sempre pode converter entre os dois formatos quando necessário: veja nosso guia sobre as diferenças entre YAML e JSON para uma comparação mais aprofundada.

Para concluir

Os erros de parse de JSON são irritantes, mas previsíveis. As mesmas cinco ou seis causas respondem pela grande maioria dos casos:

• Vírgulas sobrando
• Aspas simples
• Chaves sem aspas
• Comentários
• Caracteres BOM
• Colchetes desbalanceados

Familiarize-se com esses padrões e você vai corrigir a maioria dos erros de parse em segundos. E quando o arquivo for grande ou complexo demais para depurar a olho nu, cole-o no JSON Formatter e deixe que ele faça o trabalho. Se você quer que o JSON seja formatado automaticamente direto na aba do navegador, confira nossa comparação de extensões de JSON formatter para o Chrome.