Tratamento de erros

Erro da requisição x erro no processamento

São duas famílias diferentes, e confundi-las é a causa mais comum de integração frágil. A pergunta que separa as duas: a consulta chegou a existir?

Erro da requisição: a consulta não nasceu

O pedido foi recusado na hora. O status HTTP é diferente de 2xx, não existe id e nada foi cobrado. O corpo é sempre o mesmo envelope:

{
  "erro": "Placa inválida",
  "codigo": "PLACA_INVALIDA",
  "retryable": false,
  "request_id": "9f2c1b7e-4d52-4a1f-9d3e-7c8a5b2e1f04"
}

Todo erro da /v1 traz erro, codigo e retryable, inclusive o 404 de URL errada e o 500 inesperado. O request_id vem sempre que a requisição passou pela API (no 429 do limite de requisições ele pode não vir). Você não precisa mapear status HTTP para decidir retry: leia retryable.

Erro no processamento: a consulta nasceu e falhou depois

O POST respondeu 201 e o saldo foi debitado; a falha aconteceu depois, na base consultada. Ela aparece no GET /v1/consultas/{id} com HTTP 200 (a requisição funcionou; a consulta é que falhou) e o valor é estornado.

{
  "id": "6f1c2e2a-1b3d-4a9e-8f7c-2a1b3c4d5e6f",
  "servico": "gravame",
  "placa": "ABC1D23",
  "status": "erro",
  "schema_version": "1.0",
  "erro": "A base consultada está temporariamente indisponível. Isso costuma se resolver em alguns minutos: tente novamente.",
  "erro_codigo": "PROVIDER_UNAVAILABLE",
  "retryable": true
}

No erro de processamento, retryable tem três estados: true, false e ausente. Ausente significa que a falha não foi classificada (consultas anteriores a 02/09/2026, por exemplo): trate como definitiva e não repita automaticamente. Afirmar false sobre o que não sabemos faria você desistir de uma consulta recuperável; afirmar true faria você pagar à toa.

Por status HTTP

• 200
  A requisição funcionou

  No GET /v1/consultas/{id}, um 200 pode carregar status: "erro": a requisição deu certo, a consulta é que falhou.
• 400
  Pedido inválido

  Falta campo, formato errado, UF não atendida. Nada foi criado nem cobrado: corrija e reenvie.
• 401
  Chave ausente, inválida ou revogada

  Confira o cabeçalho Authorization. A revogação tem efeito imediato.
• 402
  Saldo insuficiente

  A resposta traz o saldo atual. Recarregue e reenvie; nada foi cobrado.
• 404
  Não encontrado, ou não é da sua conta

  Id de consulta de outro cliente (ou do outro ambiente) responde 404, nunca o dado. Também é a resposta para método ou URL trocados e para documento, imagem ou FIPE que não existe.
• 409
  Conflito

  Mesma Idempotency-Key ainda em processamento (espere e repita, sem criar outra consulta) ou aceite_atpve.versao desatualizada.
• 422
  Entendido, mas não processável

  Serviço indisponível para a conta, Idempotency-Key reusada com outro corpo, ATPV-e sem declaração, documento pedido com chave de teste ou documento armazenado inválido.
• 429
  Limite de requisições

  Respeite o Retry-After. Não consome saldo.
• 500
  Falha interna inesperada

  Transitória (retryable: true). Se insistir, envie o request_id ao suporte.
• 502
  A fonte da FIPE respondeu com erro

  Transitório. O valor já foi estornado.
• 503
  Base ou ambiente de teste indisponível

  Circuito aberto, fonte fora ou sandbox momentaneamente fora. Transitório.
• 504
  Tempo da base excedido

  Transitório. Repita depois de um intervalo.

Catálogo de erros da requisição

Lido de GET /public/api-erros (público, sem chave), a mesma fonte que o backend usa para montar as respostas. Cada código tem link próprio: /api-integradores/docs/erros#CODIGO.

Códigos de falha do processamento

Valores possíveis de erro_codigo numa consulta com status: "erro". Em todos eles o valor da consulta é estornado. A mensagem é a que vai em erro (sem nome de fornecedor).

Problemas comuns

Credencial inválida (401)

Faltou o cabeçalho Authorization: Bearer …, a chave foi revogada ou está com espaço/quebra de linha a mais (comum ao colar de um e-mail ou de um arquivo .env com aspas). No Postman, confira a aba Authorization em cada requisição.

Saldo insuficiente (402)

A carteira não cobre o preço do serviço. A resposta traz o saldo atual; recarregue na carteira e reenvie. Monitore com GET /v1/saldo para recarregar antes de acabar.

Parâmetro incorreto (400)

O codigo diz qual campo: PLACA_INVALIDA, UF_INVALIDA, CRLV_DADOS_OBRIGATORIOS… Os campos exigidos por serviço (e por UF, no CRLV) estão em requer de GET /v1/servicos: leia de lá em vez de fixar no código.

Serviço indisponível (422)

SERVICO_INDISPONIVEL significa que o serviço (ou a UF, no CRLV) não está liberado na API para a sua conta neste momento. Ele some de GET /v1/servicos enquanto estiver assim.

Consulta parada em processando

Na base estadual, a primeira consulta do dia de uma placa pode levar cerca de 2 minutos; CRLV em alguns estados e ATPV-e levam mais. Use teto de 5 minutos no polling. Se estourar, a consulta não se perdeu: guarde o id e consulte depois, ou deixe o webhook avisar.

Webhook não recebido

Confira, no portal, o histórico de entregas do endpoint (status, código HTTP e erro de cada tentativa). Causas comuns: URL sem HTTPS, endpoint desativado, resposta acima de 10 s, firewall bloqueando, assinatura recusada pelo seu código, URL apontando para rede interna. Use o botão Testar e o simulador. Enquanto isso, o polling continua funcionando.

Limite de requisições atingido (429)

Espere o Retry-After. Se acontece com frequência, o polling está apertado demais ou paralelo demais: aumente o intervalo, limite a concorrência ou troque por webhook. Ver Limites.

Resultado não encontrado

Duas situações diferentes. 404 CONSULTA_NOT_FOUND: o id não existe para esta chave (outra conta, outro ambiente, consulta de teste expirada, id digitado errado). erro_codigo: QUERY_NOT_FOUND: a consulta existiu e a base não encontrou registro para os dados enviados (placa inexistente ou digitada errada); o valor foi estornado e repetir não muda o resultado.

Falha da base consultada

PROVIDER_UNAVAILABLE, PROVIDER_TIMEOUT e CIRCUIT_OPEN são transitórios: a base caiu ou demorou. O valor foi estornado; crie uma consulta nova depois de um intervalo, com teto de tentativas. Muitas falhas seguidas no mesmo serviço costumam indicar instabilidade da base: acompanhe a página de status.

404 com codigo ROTA_NAO_ENCONTRADA

Método ou URL não batem. Quase sempre: POST com o id na URL (para ver é GET), GET em /v1/consultas sem id (para criar é POST) ou caminho digitado errado.