# Como lidar com erros comuns ao integrar uma API de consulta de CPF > Conheça os erros mais comuns ao integrar uma API de consulta de CPF e aprenda a tratá-los corretamente. HTTP 401, 404, timeout e mais. **Publicado:** 21/04/2026 **Autor:** Redação CPFHub.io **URL:** https://cpfhub.io/blog/como-lidar-com-erros-comuns-ao-integrar-uma-api-de-consulta-de-cpf --- Os erros mais comuns ao integrar uma API de consulta de CPF são: chave de autenticação ausente ou inválida (HTTP 401), CPF com formato incorreto antes da chamada, timeout por falta de configuração de prazo na requisição, e acesso ao campo `data` sem verificar o campo `success` primeiro. Cada um tem solução direta, e tratá-los corretamente é o que separa uma integração frágil de uma robusta. ## Erros HTTP mais frequentes ### 401 -- Unauthorized **Causa:** Chave de API ausente, inválida ou expirada. ```bash # Erro: sem header de autenticacao curl -X GET https://api.cpfhub.io/cpf/12345678900 # Correto: com x-api-key curl -X GET https://api.cpfhub.io/cpf/12345678900 \ -H "x-api-key: SUA_CHAVE_DE_API" \ -H "Accept: application/json" ``` **Solução:** Verifique se a chave está correta e sendo enviada no header `x-api-key`. ### 404 -- Not Found **Causa:** CPF não encontrado na base ou URL incorreta. **Solução:** Verifique se o CPF tem 11 dígitos e se a URL está no formato correto: `https://api.cpfhub.io/cpf/{cpf}`. ### 500 -- Internal Server Error **Causa:** Erro interno no servidor da API. **Solução:** Implemente retry com backoff. Se persistir, entre em contato com o suporte. ### 503 -- Service Unavailable **Causa:** API temporariamente indisponível (manutenção ou sobrecarga). **Solução:** Retry com backoff exponencial. Use cache como fallback. --- ## Erros de rede ### Timeout **Causa:** A API não respondeu dentro do prazo configurado. A latência típica da API é de cerca de 900ms — configure o timeout com folga suficiente para absorver variações de rede. ```python import requests try: response = requests.get( f'https://api.cpfhub.io/cpf/12345678900', headers={'x-api-key': 'SUA_CHAVE_DE_API', 'Accept': 'application/json'}, timeout=10 # 10 segundos ) except requests.Timeout: print('Timeout: API nao respondeu a tempo') except requests.ConnectionError: print('Erro de conexao: verifique sua rede') ``` **Solução:** Configure um timeout adequado (5-10 segundos) e implemente retry. ### SSL/TLS errors **Causa:** Problema de certificado ou versão de TLS incompatível. **Solução:** Atualize suas bibliotecas HTTP e sistema operacional. Nunca desabilite a verificação de SSL. --- ## Erros de lógica da aplicação ### CPF com formato inválido ```python def validar_formato_cpf(cpf: str) -> str: cpf_limpo = cpf.replace('.', '').replace('-', '').strip() if len(cpf_limpo) != 11: raise ValueError(f'CPF deve ter 11 digitos, recebeu {len(cpf_limpo)}') if not cpf_limpo.isdigit(): raise ValueError('CPF deve conter apenas numeros') return cpf_limpo ``` ### Não tratar resposta success: false ```python resultado = response.json() # ERRADO: acessar data sem verificar success # nome = resultado['data']['name'] # KeyError se success = false # CORRETO: verificar antes if resultado.get('success'): nome = resultado['data']['name'] else: print('CPF nao encontrado') ``` ### Comparação de nomes case-sensitive ```python # ERRADO nome_confere = nome_informado == resultado['data']['name'] # CORRETO: normalizar antes de comparar nome_confere = nome_informado.upper().strip() in resultado['data']['nameUpper'] ``` --- ## Tratamento completo de erros ```python import requests def consultar_cpf_seguro(cpf: str) -> dict: # 1. Validar formato cpf_limpo = cpf.replace('.', '').replace('-', '').strip() if len(cpf_limpo) != 11 or not cpf_limpo.isdigit(): return {'error': 'Formato de CPF invalido', 'code': 'FORMATO_INVALIDO'} # 2. Chamar API com tratamento url = f'https://api.cpfhub.io/cpf/{cpf_limpo}' headers = { 'x-api-key': 'SUA_CHAVE_DE_API', 'Accept': 'application/json' } try: response = requests.get(url, headers=headers, timeout=10) if response.status_code == 200: return response.json() elif response.status_code == 401: return {'error': 'Chave de API invalida', 'code': 'AUTH_ERROR'} elif response.status_code == 404: return {'error': 'CPF nao encontrado', 'code': 'NOT_FOUND'} else: return {'error': f'Erro HTTP {response.status_code}', 'code': 'HTTP_ERROR'} except requests.Timeout: return {'error': 'Timeout na requisicao', 'code': 'TIMEOUT'} except requests.ConnectionError: return {'error': 'Erro de conexao', 'code': 'CONNECTION_ERROR'} except Exception as e: return {'error': str(e), 'code': 'UNKNOWN_ERROR'} ``` --- ## Checklist de tratamento de erros * Timeout configurado (5-10 segundos). * Retry com backoff exponencial para erros 5xx e timeouts. * Validação local de formato antes de chamar a API. * Verificação do campo `success` antes de acessar `data`. * Tratamento de cada código HTTP (401, 404, 500, 503). * Logs de erro com detalhes suficientes para diagnóstico. * Fallback para cache ou degradação graceful. --- ## Perguntas frequentes ### Por que recebo HTTP 401 mesmo com a chave de API no código? O erro 401 indica que a chave está ausente ou inválida na requisição. Os motivos mais comuns são: o header está sendo enviado com nome errado (deve ser exatamente `x-api-key`), a chave foi regenerada no painel e o código ainda usa a anterior, ou há espaços extras na variável de ambiente. Verifique o valor com um `curl` direto antes de depurar a lógica da aplicação. ### O que fazer quando o CPF retorna 404? O HTTP 404 significa que o CPF não foi localizado na base ou que a URL da requisição está incorreta. Confirme dois pontos: o CPF tem exatamente 11 dígitos numéricos (sem pontos ou traços) e a URL segue o padrão `https://api.cpfhub.io/cpf/{cpf}`. CPFs com dígitos verificadores inválidos também tendem a retornar 404. ### Como implementar retry sem sobrecarregar a API? Use backoff exponencial com jitter: na primeira tentativa aguarde 1s, na segunda 2s, na terceira 4s, e assim por diante, adicionando um valor aleatório pequeno a cada intervalo. Limite o retry a erros 5xx e timeouts — erros 4xx (401, 404) são definitivos e não se resolvem com retry. O [guia de resiliência de APIs da OWASP](https://owasp.org/www-project-api-security/) detalha padrões de tratamento de falhas. ### Qual a diferença entre validar o CPF localmente e consultar a API? A validação local (algoritmo dos dígitos verificadores) apenas confirma se o número segue a regra matemática do CPF -- não garante que o documento existe ou pertence a quem afirma. A consulta à API retorna dados cadastrais reais (nome, data de nascimento, gênero), permitindo cruzar as informações com o que o usuário declarou. Para onboarding com verificação de identidade, a consulta à API é indispensável. ### Leia também - [Como validar CPF no frontend com React e API REST](https://cpfhub.io/blog/como-validar-cpf-no-frontend-com-react-e-api-rest) - [Boas práticas para consumir APIs de CPF de forma segura](https://cpfhub.io/blog/boas-praticas-consumir-apis-cpf-segura) - [Como consumir API de CPF em Python com FastAPI](https://cpfhub.io/blog/como-consumir-api-de-cpf-em-python-com-fastapi) - [Como criar um SDK interno para padronizar consultas de CPF na empresa](https://cpfhub.io/blog/como-criar-sdk-interno-padronizar-consultas-cpf-empresa) --- ## Conclusão Tratar erros corretamente transforma uma integração frágil em uma integração robusta. Com timeout configurado, retry com backoff, validação local de formato e tratamento individual de cada código HTTP, sua aplicação estará preparada para lidar com qualquer cenário — inclusive picos de carga e instabilidades momentâneas de rede. A [**CPFHub.io**](https://www.cpfhub.io/) oferece documentação com exemplos de tratamento de erros em Python, Node.js, PHP, Java e outras linguagens. Se você está refatorando uma integração existente ou iniciando do zero, o plano gratuito cobre as primeiras 50 consultas sem cartão de crédito — suficiente para validar todo o fluxo de tratamento de erros em ambiente de desenvolvimento. Cadastre-se em [cpfhub.io](https://www.cpfhub.io/) e comece a testar agora.