# Erros

Todo erro vem com o HTTP correto e este corpo:

```json
{
  "erro": {
    "codigo": "placa_nao_encontrada",
    "mensagem": "Nenhum veículo encontrado para esta placa. Nenhum crédito foi descontado.",
    "docs": "https://placaefipe.com.br/docs/erros#placa_nao_encontrada"
  }
}
```

Use sempre `erro.codigo` na sua lógica. A `mensagem` pode mudar de texto.

**Nenhum erro consome crédito.**

## Tabela

| HTTP | `erro.codigo` | O que fazer |
|---|---|---|
| 400 | `placa_invalida` | Peça ao usuário para conferir a placa. Formato: `ABC1234` ou `ABC1D23`. Não tente de novo. |
| 401 | `nao_autenticado` | Envie `Authorization: Bearer pf_live_...`. |
| 401 | `chave_invalida` | A chave está errada ou foi revogada. Gere outra no painel. |
| 402 | `sem_creditos` | Saldo zerado. Compre um pacote e avise o administrador do sistema. |
| 404 | `placa_nao_encontrada` | Mostre "veículo não encontrado". Não tente de novo antes de 24 h. |
| 429 | `limite_excedido` | Muitas requisições por segundo. Espere 1 s e tente de novo. |
| 429 | `limite_da_chave` | A chave chegou ao limite mensal definido no painel. Aumente o limite ou use outra chave. |
| 503 | `indisponivel` | Instabilidade temporária. Tente de novo em 2 a 5 s (até 3 vezes). |
| 500 | `erro_interno` | Erro inesperado. Tente de novo; se repetir, fale com o suporte com o horário. |

## placa_invalida

A placa não segue o padrão antigo (3 letras e 4 números) nem o Mercosul (3 letras, 1 número, 1 letra e 2 números). Traço, espaço e minúsculas são removidos antes da validação.

## nao_autenticado

Nenhuma chave foi enviada. Veja [Autenticação](/docs/autenticacao).

## chave_invalida

A chave não existe ou foi revogada no painel.

## sem_creditos

A conta está sem saldo. Compre créditos em [Preços](/precos). Os créditos entram assim que o pagamento é aprovado.

## placa_nao_encontrada

Não há registro para essa placa. Placas muito novas podem levar alguns dias para aparecer.

## limite_excedido

O limite é de 10 requisições por segundo por chave (20 no plano Escala). Para lotes grandes, faça as chamadas em fila.

## limite_da_chave

A chave atingiu o limite mensal de créditos que você definiu ao criá-la. Não adianta repetir: aumente o limite no painel, use outra chave ou espere o mês virar.

## indisponivel

A fonte de dados não respondeu a tempo. Repita com espera crescente:

```js
async function consultarComRetry(placa, tentativas = 3) {
  for (let i = 0; i < tentativas; i++) {
    const r = await fetch(`https://api.placaefipe.com.br/v1/placas/${placa}`, {
      headers: { Authorization: `Bearer ${process.env.PLACAEFIPE_API_KEY}` },
    });
    if (r.status !== 503 && r.status !== 429) return r;
    await new Promise((ok) => setTimeout(ok, 1000 * 2 ** i));
  }
  throw new Error('Placa & FIPE indisponível');
}
```

## erro_interno

Erro do nosso lado. Nenhum crédito foi descontado.