Erros HTTP

Erros 401, 402, 404 e 429 na API CPF: como resolver

Descubra o significado dos erros HTTP 401, 402, 404 e 429 da API CPF e como tratá-los corretamente no backend.

Imagem editorial sobre Diagnóstico de respostas HTTP
Diagnóstico de respostas HTTP.

Entenda os códigos de erro de uma API de CPF

Ao integrar consulta de CPF, devolver sempre “tente novamente” é ruim para usuário e suporte. Os códigos 401, 402, 404 e 429 indicam causas distintas. O contrato oficial informa que erros incluem code e message, mas seu sistema também deve prever HTML inesperado, JSON inválido e falhas de rede.

401: erro de autenticação

Significa API Key ausente ou inválida. Verifique X-API-KEY, variável de ambiente, credencial regenerada e domínio api.apicpf.dev. Não repita com a mesma chave indefinidamente e nunca exiba a credencial na mensagem retornada ao cliente.

402: sem créditos disponíveis

Esse status aponta falta de créditos. Consulte o painel e as condições do plano. Repetir a requisição sem ajuste de créditos não corrige a causa. Uma validação matemática anterior à consulta pode poupar chamadas desnecessárias.

404: rota não encontrada

A documentação pública associa 404 a rota não encontrada. Verifique caminho /consulta, método GET, parâmetro cpf e a mensagem no corpo. Outros sistemas podem empregar 404 para ausência de recurso, mas o número isolado não prova que um CPF inexiste.

429: limite de requisições atingido

Limites RPM/diário variam por contexto e plano. Reduza o ritmo; use fila, limites de concorrência e espera crescente com jitter. Se aparecer Retry-After, você pode respeitá-lo, mas não assuma a presença desse cabeçalho. Consulte também o guia de backoff.

Outros códigos documentados

Código Significado O que fazer
400 CPF inválido ou mal formatado Verificar entrada
403 Conta bloqueada ou IP fora da allowlist Rever acesso
500 Falha interna / banco indisponível Registrar evento técnico e investigar

Exemplo de classificação em JavaScript

function acao(status) {
  if (status === 401) return "revisar-chave";
  if (status === 402) return "verificar-creditos";
  if (status === 404) return "verificar-rota-e-mensagem";
  if (status === 429) return "reprogramar-com-backoff";
  if (status >= 500) return "falha-temporaria";
  return "revisar-entrada-ou-resposta";
}

Seu frontend não precisa exibir esses códigos internos. Pode informar que não foi possível concluir a consulta, enquanto o backend registra apenas status, duração e identificador de correlação, sem CPF completo, URL de consulta nem chave.

Checklist para depurar uma falha

  1. Confira host, método, caminho e header de autenticação.
  2. Inspecione code e message sem copiar informações pessoais para tickets públicos.
  3. Classifique erros recuperáveis e definitivos.
  4. Evite retries para 401 e 402; limite tentativas em 429 e 5xx.
  5. Monitore frequência dos status por operação para localizar regressões.

Perguntas frequentes

404 significa CPF não encontrado?

Não necessariamente. O significado deve seguir o contrato da rota e a mensagem retornada, não apenas o status HTTP.

Posso repetir um 429 imediatamente?

Não é recomendado. Isso pode agravar a limitação e criar uma tempestade de tentativas.

Continue aprendendo