# API de CPF: como tratar respostas de erro (4xx e 5xx) de forma robusta > Aprenda a tratar erros HTTP 4xx e 5xx ao consultar CPF via API. Veja exemplos de tratamento para cada código de status. **Publicado:** 03/04/2025 **Autor:** Redação CPFHub.io **URL:** https://cpfhub.io/blog/api-de-cpf-como-tratar-respostas-de-erro-4xx-e-5xx-de-forma-robusta --- Ao integrar a API da [**CPFHub.io**](https://www.cpfhub.io/), classifique os erros em dois grupos: erros do cliente (4xx), que exigem correção na sua aplicação, e erros do servidor (5xx), que são transitórios e admitem retry com backoff exponencial. O [OWASP API Security Top 10](https://owasp.org/API-Security/editions/2023/en/0x11-t10/) recomenda tratar cada código de status de forma explícita para evitar que falhas silenciosas comprometam a segurança e a rastreabilidade da integração. ## Introdução Toda integração com APIs externas precisa lidar com cenários de erro. Enquanto a resposta de sucesso (HTTP 200) é o caminho feliz, os códigos de erro 4xx e 5xx representam situações que sua aplicação deve tratar de forma específica e informativa. Ignorar ou tratar genericamente esses erros resulta em experiências ruins para o usuário e dificulta a investigação de problemas. --- ## Códigos de resposta da API A API da [**CPFHub.io**](https://www.cpfhub.io/) retorna os seguintes códigos de status: | Código | Significado | Tipo | Ação recomendada | | --- | --- | --- | --- | | 200 | OK | Sucesso | Processar os dados retornados | | 400 | Bad Request | Erro do cliente | Verificar formato do CPF enviado | | 401 | Unauthorized | Erro do cliente | Verificar a API key | | 404 | Not Found | Erro do cliente | CPF não encontrado na base | | 500 | Internal Server Error | Erro do servidor | Retry com backoff | | 503 | Service Unavailable | Erro do servidor | Retry com backoff | --- ## Erros 4xx: problemas no lado do cliente Os erros 4xx indicam que o problema está na requisição enviada. A correção deve ser feita na sua aplicação. ### 400 Bad Request Indica que o CPF enviado tem formato inválido. Causas comuns: * CPF com menos ou mais de 11 dígitos. * Caracteres não numéricos na URL (pontos, traços). * URL mal formatada. **Prevenção:** Valide o CPF sintaticamente antes de enviar à API. ### 401 Unauthorized A chave de API está ausente, incorreta ou expirada. Causas comuns: * Header `x-api-key` não incluído na requisição. * Chave de API com erro de digitação. * Chave que foi revogada ou expirou. **Prevenção:** Armazene a chave em variável de ambiente e verifique periodicamente sua validade no painel app.cpfhub.io. ### 404 Not Found O CPF consultado não foi encontrado na base de dados. Isso não é necessariamente um erro da aplicação — significa que o CPF não possui dados cadastrais associados. **Tratamento:** Informe ao usuário que o CPF não foi localizado e permita a inserção manual dos dados, se aplicável. --- ## Erros 5xx: problemas no lado do servidor Os erros 5xx indicam que algo deu errado no servidor da API. Esses erros são tipicamente transitórios. ### 500 Internal Server Error Erro genérico do servidor. Pode ocorrer em momentos de instabilidade. **Tratamento:** Retry automático com backoff exponencial. Se persistir após 3 tentativas, acionar fallback. ### 503 Service Unavailable O serviço está temporariamente indisponível, geralmente por manutenção programada ou sobrecarga momentânea. **Tratamento:** Similar ao 500 — retry com backoff. Em caso de manutenção prolongada, verificar a status page. --- ## Implementação completa em Python ```python import requests import time import random import logging logger = logging.getLogger("cpf_api") class CPFApiError(Exception): def __init__(self, codigo, mensagem, retentavel=False): self.codigo = codigo self.mensagem = mensagem self.retentavel = retentavel super().__init__(mensagem) def tratar_resposta(response): status = response.status_code if status == 200: dados = response.json() if dados.get("success"): return dados return dados if status == 400: raise CPFApiError(400, "CPF com formato inválido", retentavel=False) if status == 401: raise CPFApiError(401, "Chave de API inválida ou ausente", retentavel=False) if status == 404: raise CPFApiError(404, "CPF não encontrado na base", retentavel=False) if status == 500: raise CPFApiError(500, "Erro interno do servidor", retentavel=True) if status == 503: raise CPFApiError(503, "Serviço temporariamente indisponível", retentavel=True) raise CPFApiError(status, f"Erro inesperado: HTTP {status}", retentavel=False) def consultar_cpf(cpf, max_tentativas=3): url = f"https://api.cpfhub.io/cpf/{cpf}" headers = { "x-api-key": "SUA_CHAVE_DE_API", "Accept": "application/json" } for tentativa in range(max_tentativas): try: response = requests.get(url, headers=headers, timeout=10) return tratar_resposta(response) except CPFApiError as e: logger.warning(f"Tentativa {tentativa + 1}: {e.mensagem} (HTTP {e.codigo})") if not e.retentavel or tentativa == max_tentativas - 1: raise espera = (2 ** tentativa) + random.uniform(0, 1) logger.info(f"Aguardando {espera:.1f}s antes de nova tentativa...") time.sleep(espera) except requests.exceptions.Timeout: logger.warning(f"Tentativa {tentativa + 1}: timeout") if tentativa == max_tentativas - 1: raise CPFApiError(0, "Timeout após todas as tentativas", retentavel=False) espera = (2 ** tentativa) + random.uniform(0, 1) time.sleep(espera) # Uso com tratamento de cada tipo de erro try: resultado = consultar_cpf("12345678900") print(f"Sucesso: {resultado}") except CPFApiError as e: if e.codigo == 400: print("Verifique o formato do CPF informado.") elif e.codigo == 401: print("Verifique sua chave de API no painel CPFHub.io.") elif e.codigo == 404: print("CPF não encontrado. Solicite os dados manualmente.") else: print(f"Erro: {e.mensagem}") ``` --- ## Implementação completa em JavaScript (Node.js) ```javascript class CPFApiError extends Error { constructor(codigo, mensagem, retentavel = false) { super(mensagem); this.codigo = codigo; this.retentavel = retentavel; } } function tratarResposta(response, dados) { const status = response.status; if (status === 200) return dados; if (status === 400) throw new CPFApiError(400, 'CPF com formato inválido'); if (status === 401) throw new CPFApiError(401, 'API key inválida ou ausente'); if (status === 404) throw new CPFApiError(404, 'CPF não encontrado'); if (status === 500) throw new CPFApiError(500, 'Erro interno do servidor', true); if (status === 503) throw new CPFApiError(503, 'Serviço indisponível', true); throw new CPFApiError(status, `Erro inesperado: HTTP ${status}`); } async function consultarCPF(cpf, maxTentativas = 3) { const url = `https://api.cpfhub.io/cpf/${cpf}`; for (let tentativa = 0; tentativa < maxTentativas; tentativa++) { const controller = new AbortController(); const timeoutId = setTimeout(() => controller.abort(), 10000); try { const response = await fetch(url, { headers: { 'x-api-key': 'SUA_CHAVE_DE_API', 'Accept': 'application/json' }, signal: controller.signal }); clearTimeout(timeoutId); const dados = await response.json(); return tratarResposta(response, dados); } catch (error) { clearTimeout(timeoutId); if (error instanceof CPFApiError) { if (!error.retentavel || tentativa === maxTentativas - 1) throw error; const espera = Math.pow(2, tentativa) * 1000 + Math.random() * 1000; await new Promise(r => setTimeout(r, espera)); continue; } if (error.name === 'AbortError') { if (tentativa === maxTentativas - 1) { throw new CPFApiError(0, 'Timeout após todas as tentativas'); } const espera = Math.pow(2, tentativa) * 1000; await new Promise(r => setTimeout(r, espera)); continue; } throw error; } } } ``` --- ## Mensagens de erro para o usuário final O tratamento de erros deve traduzir códigos HTTP técnicos em mensagens compreensíveis para o usuário: | Código | Mensagem técnica | Mensagem para o usuário | | --- | --- | --- | | 400 | Bad Request | O CPF informado não é válido. Verifique e tente novamente. | | 401 | Unauthorized | Erro interno. Tente novamente mais tarde. | | 404 | Not Found | Não foi possível localizar dados para este CPF. | | 500 | Internal Server Error | Estamos com dificuldades técnicas. Tente novamente. | | 503 | Service Unavailable | Serviço em manutenção. Tente novamente em alguns minutos. | Note que erros 401 não devem expor detalhes sobre a chave de API ao usuário final — apenas registre internamente. --- ## Perguntas frequentes ### A CPFHub.io bloqueia requisições quando o plano é excedido? Não. A CPFHub.io nunca retorna HTTP 429 nem bloqueia chamadas. Ao ultrapassar a cota do plano, cada consulta adicional é cobrada a R$0,15 e a API continua respondendo normalmente. Não é necessário implementar lógica de backoff por cota — reserve o retry apenas para erros 5xx transitórios. ### Quais erros HTTP devo tratar como retentáveis? Apenas os erros 5xx (500 e 503) são retentáveis, pois indicam falhas transitórias do servidor. Erros 4xx (400, 401, 404) indicam problemas na requisição e não se resolvem com retry — corrija a causa raiz na aplicação antes de tentar novamente. ### Como implementar backoff exponencial corretamente? A estratégia padrão é aguardar `2^tentativa + jitter_aleatório` segundos entre cada retry. Para a CPFHub.io, um limite de 3 tentativas com intervalos de 1s, 2s e 4s (mais jitter) é suficiente para cobrir instabilidades transitórias sem atrasar excessivamente o fluxo da aplicação. ### O que fazer quando a API retorna HTTP 401 em produção? Um 401 em produção normalmente indica que a chave de API expirou ou foi revogada. Verifique o painel em app.cpfhub.io, gere uma nova chave se necessário e atualize a variável de ambiente da aplicação. Nunca exponha o detalhe do erro 401 ao usuário final — registre internamente e exiba uma mensagem genérica. ### Leia também - [SLA de API de CPF: níveis de disponibilidade e o que exigir do seu provedor](https://cpfhub.io/blog/sla-api-cpf-niveis-disponibilidade) - [Como fazer fallback automático quando a API de CPF está fora do ar](https://cpfhub.io/blog/como-fazer-fallback-automatico-quando-a-api-de-cpf-esta-fora-do-ar) - [Guia de headers HTTP obrigatórios para consumir API de CPF corretamente](https://cpfhub.io/blog/guia-de-headers-http-obrigatorios-para-consumir-api-de-cpf-corretamente) - [API de CPF grátis para desenvolvedores: como começar em 5 minutos](https://cpfhub.io/blog/api-cpf-gratis-desenvolvedores-comecar-5-minutos) --- ## Conclusão Tratar respostas de erro de forma robusta é o que diferencia uma integração amadora de uma integração profissional. Ao classificar os erros entre retentáveis e não retentáveis, implementar retry inteligente para erros transitórios e traduzir códigos HTTP em mensagens claras para o usuário, sua aplicação se torna mais resiliente e mais fácil de depurar. Cadastre-se em [cpfhub.io](https://www.cpfhub.io/) — 50 consultas mensais gratuitas, sem cartão de crédito — e implemente tratamento de erros profissional desde a primeira linha de código.