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
- Confira host, método, caminho e header de autenticação.
- Inspecione
codeemessagesem copiar informações pessoais para tickets públicos. - Classifique erros recuperáveis e definitivos.
- Evite retries para 401 e 402; limite tentativas em 429 e 5xx.
- 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.
