JSON para iniciantes: o que é, como ler e os erros mais comuns

Atualizado em 3 de novembro de 2026 · Leitura de 5 min

Edson Feitosa de Oliveira Junior Fundador e Engenheiro Líder · PruPru Digital Services

JSON (JavaScript Object Notation) é o formato mais usado para trocar dados entre sistemas. Quando um aplicativo busca informações em uma API, quando um provedor de pagamento envia uma notificação ou quando uma ferramenta guarda suas configurações, há grandes chances de o formato ser JSON. Ele é simples de ler para pessoas e fácil de processar para programas, e entendê-lo bem evita uma série de erros bobos que consomem horas.

A estrutura básica

Um documento JSON é formado por dois tipos de estrutura:

• Objeto: um conjunto de pares chave e valor, entre chaves { }.
• Lista (array): uma sequência ordenada de valores, entre colchetes [ ].

Exemplo de um pedido:

{
  "id": 8231,
  "cliente": {
    "nome": "Ana Souza",
    "email": "ana@exemplo.com"
  },
  "itens": [
    { "produto": "Cabo HDMI", "quantidade": 2, "preco": 29.90 },
    { "produto": "Mouse sem fio", "quantidade": 1, "preco": 89.00 }
  ],
  "pago": true,
  "cupom": null
}

Tipos de dados

Não existe tipo de data em JSON. Datas são enviadas como texto, de preferência no formato ISO 8601: "2026-11-02T14:03:22Z".

As regras de sintaxe que mais pegam

1. Chaves sempre entre aspas duplas: "nome": "Ana", nunca nome: "Ana".
2. Aspas duplas, não simples: 'Ana' é inválido.
3. Sem vírgula depois do último item: [1, 2, 3,] é inválido em JSON, embora seja aceito em JavaScript.
4. Sem comentários: JSON não aceita // nem /* */.
5. Números sem zeros à esquerda e com ponto: 29.90, não 29,90.
6. Caracteres especiais escapados: aspas dentro do texto viram \", quebras de linha viram \n.

A maioria dos erros "Unexpected token" vem de uma dessas regras.

Lendo JSON em JavaScript

const texto = '{"nome": "Ana", "idade": 30}';
const pessoa = JSON.parse(texto);     // texto para objeto
console.log(pessoa.nome);             // Ana

const json = JSON.stringify(pessoa, null, 2);  // objeto para texto formatado

Com o fetch:

const resposta = await fetch("/api/pedidos/8231");
if (!resposta.ok) throw new Error("Erro " + resposta.status);
const pedido = await resposta.json();
console.log(pedido.itens.length);

Verifique sempre o status antes de converter: uma página de erro em HTML não é JSON e gera "Unexpected token <". Veja códigos de status HTTP e JavaScript para iniciantes.

Lendo JSON em Java

No Spring Boot, a conversão é automática com a biblioteca Jackson. Basta criar uma classe ou um record com os mesmos campos:

public record Item(String produto, int quantidade, BigDecimal preco) {}
public record Pedido(Long id, List<Item> itens, boolean pago) {}

@PostMapping("/pedidos")
public ResponseEntity<Pedido> criar(@RequestBody Pedido pedido) {
    // pedido já convertido do JSON
    return ResponseEntity.status(201).body(pedido);
}

Se o JSON enviado estiver malformado ou com tipos incompatíveis, o Spring responde 400 com uma HttpMessageNotReadableException no log. Veja sua primeira API com Spring Boot e como ler uma stack trace Java.

Erros de dados que causam bugs

Dinheiro como número de ponto flutuante

Em muitas linguagens, 0.1 + 0.2 não dá exatamente 0.3. Para valores monetários, use tipos decimais no código (BigDecimal em Java) ou envie o valor em centavos, como número inteiro ("preco_centavos": 2990). Muitas APIs de pagamento usam centavos por esse motivo.

Datas sem fuso horário

"2026-11-02 14:00" é ambíguo: 14h em qual fuso? Prefira ISO 8601 com o fuso explícito (Z para UTC ou -03:00).

Números grandes demais

Identificadores muito longos podem perder precisão em JavaScript, que representa números com limite de precisão. Por isso, muitas APIs enviam identificadores grandes como texto.

Campos nulos versus ausentes

"cupom": null e a ausência do campo cupom podem significar coisas diferentes para a API. Combine e documente o comportamento.

Nomes inconsistentes

Misturar nomeCliente, nome_cliente e NomeCliente em uma mesma API confunde quem consome. Escolha um padrão (camelCase ou snake_case) e siga.

Ferramentas úteis

• Ferramentas de desenvolvedor do navegador: a aba Network mostra o JSON de cada resposta, já formatado.
• Formatadores e validadores: muitas IDEs e editores formatam e apontam erros de sintaxe. Evite colar JSON com dados pessoais ou chaves em sites desconhecidos.
• jq no terminal: curl -s https://api.exemplo.com/pedidos | jq '.[0].cliente'. Veja comandos Linux básicos.
• JSON Schema: define formalmente o formato esperado e permite validar dados automaticamente.

JSON no dia a dia além das APIs

Arquivos de configuração (package.json, configurações de editores), logs estruturados, webhooks e o conteúdo de tokens JWT também usam JSON. Até o Google lê dados estruturados em JSON-LD nas páginas para entender o conteúdo de um site, o que ajuda no SEO.

Perguntas frequentes