Erros
Todo erro vem com o HTTP correto e este corpo:
{
"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.
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. 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:
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.