← Todos os artigos
Atualizado em May 29, 20265 min read

Caractere de escape inválido em JSON: escapes válidos e correções

Um caractere mal escapado em JSON significa que uma barra invertida é seguida por algo que JSON não permite. Veja a lista completa de escapes válidos, além de correções para \x, caminhos e \u.

SyntaxError: Bad escaped character in JSON at position N significa que há uma barra invertida (\) dentro de uma string seguida por algo que o JSON não reconhece como escape válido. JSON só permite um conjunto pequeno e fixo de sequências de escape —— qualquer outra coisa depois de uma \ dispara este erro. Aqui está a lista completa e como corrigir.

Qual erro de string estou vendo?

Como o erro aparece

// V8 (Chrome / Node / Edge)
SyntaxError: Bad escaped character in JSON at position 14

// Firefox
SyntaxError: JSON.parse: bad escaped character at line 1 column 15 of the JSON data

// Safari
SyntaxError: JSON Parse error: Invalid escape character \x

Os únicos escapes que o JSON aceita

Dentro de uma string JSON, uma barra invertida só pode ser seguida por exatamente um destes:

\"   aspas duplas
\\   barra invertida
\/   barra normal
\b   backspace
\f   form feed
\n   nova linha
\r   retorno de carro
\t   tabulação
\uXXXX   um ponto de código Unicode (exatamente 4 dígitos hex)

Qualquer outra coisa depois de uma \ —— \x, \', \a, \0, um caminho Windows como \Users ou um \u12 malformado —— conta como „bad escaped character“.

Por que acontece

Causa 1 —— Emprestar escapes de outras linguagens

// ❌ \x e \' são válidos em JS/Python, não em JSON
{ "code": "\x1b[0m", "name": "O\'Brien" }

// ✅ use um escape \u para o byte e não escape apóstrofos
{ "code": "\u001b[0m", "name": "O'Brien" }

Causa 2 —— Caminhos de arquivo Windows

// ❌ cada barra invertida abre um escape inválido
{ "path": "C:\Users\Ada\file.json" }

// ✅ escape cada barra (ou use barras normais)
{ "path": "C:\\Users\\Ada\\file.json" }
{ "path": "C:/Users/Ada/file.json" }

Causa 3 —— Escape \u truncado ou malformado

// ❌ \u precisa de exatamente 4 dígitos hex
{ "char": "\u12" }

// ✅
{ "char": "\u0012" }

Pares substitutos e caracteres fora do BMP

O escape \uXXXX do JSON é fixo em 4 dígitos hex, o que endereça pontos de código até U+FFFF (o Plano Multilíngue Básico). Caracteres acima disso —— emojis, muitas extensões CJK, símbolos matemáticos —— precisam ser escritos como um par substituto UTF-16:

// 😀 (U+1F600) como par substituto
"\uD83D\uDE00"

// não permitido —— JSON não tem \U nem \u{...}
"\u1F600"     // escape inválido (só os 4 primeiros hex são consumidos; o resto vira texto)
"\u{1F600}"   // escape inválido

Esta é a codificação do JSON na forma UTF-16, mesmo que o arquivo em disco esteja em UTF-8. Duas consequências práticas:

  • UTF-8 no arquivo está OK. Você pode escrever "😀" literalmente; parsers modernos lidam com isso. A forma de par substituto só é necessária quando você precisa escapar.
  • Cuidado com substitutos solitários. Um \uD83D sem seu substituto baixo correspondente, ou vice-versa, é tecnicamente permitido pelo JSON mas é UTF-16 malformado —— consumidores a jusante (especialmente o jsonb do Postgres) vão rejeitar. JSON.stringify só produz pares bem formados.

Como corrigir —— passo a passo

  1. Pule para a posição reportada e encontre a \ que precede o caractere inválido.
  2. É uma barra invertida solta? (ex.: caminho Windows) —— dobre para \\ ou mude para barras normais.
  3. É um escape estrangeiro tipo \x ou \'? —— converta \xNN para \u00NN e remova a barra invertida antes de '.
  4. É um \u curto? —— preencha para exatamente quatro dígitos hex.
  5. Melhor correção: construa o JSON com JSON.stringify(), que só produz escapes válidos.
// Prevenção —— o escape correto é automático
JSON.stringify({ path: 'C:\\Users\\Ada', code: '\x1b[0m' });
// → {"path":"C:\\Users\\Ada","code":"\u001b[0m"}

Perguntas frequentes

O que „Bad escaped character in JSON“ significa?

Uma barra invertida dentro de uma string é seguida por um caractere que não está entre os escapes permitidos pelo JSON (" \\ / b f n r t ou \uXXXX). Os culpados comuns são \x, \' e caminhos Windows não escapados.

Como coloco um caminho Windows em JSON?

Dobre cada barra invertida (C:\\\\Users) para que cada uma seja um escape \\ válido, ou use barras normais (C:/Users), que o JSON aceita.

Isso é o mesmo que „Bad control character“?

Não. „Bad escaped character“ é sobre uma sequência inválida depois de uma barra invertida; „bad control character“ é sobre um byte de controle bruto e não escapado (tab, quebra de linha) sem nenhuma barra invertida.

Corrija agora