# API de CPF: guia completo de códigos de status e mensagens de erro > Guia completo de códigos de status HTTP e mensagens de erro da API de CPF. Aprenda a tratar cada cenário de forma adequada no seu código. **Publicado:** 22/05/2026 **Autor:** Redação CPFHub.io **URL:** https://cpfhub.io/blog/api-de-cpf-guia-completo-de-codigos-de-status-e-mensagens-de-erro --- A API de CPF da CPFHub.io usa códigos HTTP padrão: 200 para sucesso, 400 para CPF mal formatado, 401 para chave inválida e 500/503 para falhas temporárias do servidor. Cada código exige uma ação diferente no código — 400 nunca deve ser retentado, enquanto 500 e 503 aceitam retry com backoff exponencial. Tratar esses cenários corretamente é o que diferencia uma integração robusta de uma que gera falhas silenciosas e dados inconsistentes. A referência completa de status HTTP da [MDN Web Docs](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status) é útil para entender a semântica exata de cada código. --- ## Códigos de status HTTP A API da CPFHub.io utiliza códigos HTTP padronizados para indicar o resultado de cada requisição. | Código | Nome | Descrição | | --- | --- | --- | | 200 | OK | Requisição bem-sucedida. Os dados do CPF foram retornados. | | 400 | Bad Request | O formato da requisição é inválido. CPF malformado ou parâmetros incorretos. | | 401 | Unauthorized | A chave de API (x-api-key) é inválida ou está ausente. | | 404 | Not Found | O recurso solicitado não foi encontrado. | | 500 | Internal Server Error | Erro interno no servidor da API. | | 503 | Service Unavailable | A API está temporariamente indisponível. | --- ## Status 200 -- Requisição bem-sucedida O status 200 indica que a requisição foi processada com sucesso. Mesmo assim, é importante verificar o campo `success` na resposta. ### Resposta com dados encontrados ```json { "success": true, "data": { "cpf": "12345678900", "name": "Maria Silva Santos", "nameUpper": "MARIA SILVA SANTOS", "gender": "F", "birthDate": "20/03/1985", "day": 20, "month": 3, "year": 1985 } } ``` ### Resposta sem dados encontrados ```json { "success": false } ``` ### Tratamento ```python import requests def consultar_cpf(cpf: str) -> dict: url = f'https://api.cpfhub.io/cpf/{cpf}' headers = { 'x-api-key': 'SUA_CHAVE_DE_API', 'Accept': 'application/json' } response = requests.get(url, headers=headers, timeout=10) if response.status_code == 200: dados = response.json() if dados.get('success'): return {'status': 'encontrado', 'dados': dados['data']} else: return {'status': 'nao_encontrado', 'motivo': 'CPF nao localizado na base'} return {'status': 'erro', 'codigo': response.status_code} ``` --- ## Status 400 -- Bad Request O status 400 indica que a requisição contém um erro de formato. Geralmente ocorre quando o CPF é enviado em formato inválido. ### Causas comuns * **CPF com menos de 11 dígitos** -- O CPF deve ter exatamente 11 dígitos numéricos. * **CPF com caracteres não numéricos** -- Pontos, traços e espaços devem ser removidos antes do envio. * **CPF com dígitos verificadores inválidos** -- O algoritmo de validação dos dígitos verificadores falhou. ### Prevenção ```python import re def limpar_cpf(cpf: str) -> str: return re.sub(r'\D', '', cpf) def validar_formato_cpf(cpf: str) -> bool: cpf = limpar_cpf(cpf) if len(cpf) != 11: return False if cpf == cpf[0] * 11: return False # Validar digitos verificadores for i in range(9, 11): soma = sum(int(cpf[j]) * ((i + 1) - j) for j in range(i)) digito = (soma * 10) % 11 if digito == 10: digito = 0 if int(cpf[i]) != digito: return False return True # Uso cpf_bruto = '123.456.789-00' cpf_limpo = limpar_cpf(cpf_bruto) if validar_formato_cpf(cpf_limpo): resultado = consultar_cpf(cpf_limpo) else: print('CPF com formato invalido') ``` --- ## Status 401 -- Unauthorized O status 401 indica que a autenticação falhou. Isso acontece quando o header `x-api-key` está ausente, vazio ou contém uma chave inválida. ### Causas comuns * **Header ausente** -- A requisição foi feita sem o header `x-api-key`. * **Chave expirada** -- A chave de API foi revogada ou expirou. * **Chave incorreta** -- Erro de digitação ou uso de chave de outro ambiente. ### Tratamento ```python def consultar_com_tratamento_auth(cpf: str, api_key: str) -> dict: url = f'https://api.cpfhub.io/cpf/{cpf}' headers = { 'x-api-key': api_key, 'Accept': 'application/json' } response = requests.get(url, headers=headers, timeout=10) if response.status_code == 401: return { 'erro': 'Autenticacao falhou', 'acao': 'Verifique sua chave de API no painel app.cpfhub.io' } return response.json() ``` --- ## Status 500 e 503 -- Erros do servidor Erros 500 (Internal Server Error) e 503 (Service Unavailable) indicam problemas no lado da API. São erros temporários que geralmente se resolvem em poucos minutos. ### Tratamento com retry e backoff exponencial ```python import time def consultar_com_retry(cpf: str, max_tentativas: int = 3) -> dict: 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): response = requests.get(url, headers=headers, timeout=10) if response.status_code == 200: return response.json() if response.status_code in (500, 503): espera = (2 ** tentativa) * 5 # 5s, 10s, 20s print(f'Erro de servidor. Aguardando {espera}s antes de retentar...') time.sleep(espera) continue # Outros erros: nao retentar return {'erro': f'Status {response.status_code}'} return {'erro': 'Erro de servidor apos multiplas tentativas'} ``` ### Tratamento em JavaScript ```javascript async function consultarComFallback(cpf) { const controller = new AbortController(); const timeoutId = setTimeout(() => controller.abort(), 10000); try { const response = await fetch( `https://api.cpfhub.io/cpf/${cpf}`, { headers: { 'x-api-key': 'SUA_CHAVE_DE_API', 'Accept': 'application/json' }, signal: controller.signal } ); clearTimeout(timeoutId); if (response.status === 500 || response.status === 503) { return { sucesso: false, erro: 'API temporariamente indisponivel', acao: 'Tente novamente em alguns minutos', codigo: response.status }; } if (response.status === 401) { return { sucesso: false, erro: 'Chave de API invalida', acao: 'Verifique sua chave no painel app.cpfhub.io' }; } return await response.json(); } catch (error) { clearTimeout(timeoutId); if (error.name === 'AbortError') { return { sucesso: false, erro: 'Timeout na requisicao' }; } return { sucesso: false, erro: error.message }; } } ``` --- ## Tabela de tratamento recomendado | Código | Retentar? | Espera | Ação | | --- | --- | --- | --- | | 200 | Não | -- | Processar resposta normalmente | | 400 | Não | -- | Corrigir formato do CPF e tentar novamente | | 401 | Não | -- | Verificar chave de API | | 404 | Não | -- | Recurso não existe | | 500 | Sim | 5-10 segundos | Retentar até 3 vezes | | 503 | Sim | 10-30 segundos | Retentar até 3 vezes | --- ## Boas práticas gerais * **Sempre defina timeout** -- Configure timeout em todas as requisições (recomendado: 10 segundos) para evitar que sua aplicação fique travada. A latência média da API é de ~900ms. * **Valide o CPF antes de enviar** -- Use validação sintática local antes de chamar a API. Isso evita erros 400 e economiza consultas do plano. * **Registre todos os erros** -- Mantenha logs com o código de status, a mensagem de erro e o timestamp para facilitar a depuração. * **Implemente circuit breaker** -- Quando a API retornar erros 500/503 consecutivos, pare de fazer chamadas por um período e notifique a equipe. * **Monitore a taxa de erros** -- Se a taxa de erros ultrapassar 5%, investigue a causa. Pode ser um problema na sua chave, no formato das requisições ou na API. --- ## Perguntas frequentes ### O que significa a API retornar 200 com `"success": false`? Um status 200 com `success: false` indica que a requisição foi processada com sucesso pela API, mas o CPF não foi localizado na base de dados. Não é um erro de integração — é um resultado válido. Trate esse caso separando a lógica de "erro de comunicação" (4xx, 5xx, timeout) da lógica de "CPF não encontrado" (200 + success false) no seu código. ### Quando devo retentar após um erro e quando devo desistir imediatamente? Retente apenas erros temporários do servidor (500, 503) com backoff exponencial de 5 a 30 segundos, por no máximo 3 tentativas. Nunca retente automaticamente erros 400 (o CPF está mal formatado — corrigir antes de tentar de novo) nem 401 (a chave é inválida — retentar apenas piora). Erros 400 e 401 são determinísticos: o mesmo request vai retornar o mesmo erro. ### A API cobra extra quando atinge o limite de consultas mensais? A API da CPFHub.io não bloqueia ao atingir o limite do plano — ela continua respondendo e cobra R$0,15 por consulta adicional. No plano gratuito (50 consultas/mês) e Pro (R$149/mês, 1.000 consultas), o excedente é faturado automaticamente. Por isso, monitore o consumo em `app.cpfhub.io/settings/billing` para evitar surpresas na fatura. ### Como identificar se o problema está na minha integração ou na API? Se o erro é 400, o problema está no seu código — CPF mal formatado ou header ausente. Se é 401, a chave está errada ou ausente. Se é 500 ou 503, o problema está na API. Para distinguir problemas intermitentes de problemas persistentes, registre o código de status, o timestamp e o CPF consultado em cada chamada. Padrões de erro em horários específicos costumam indicar instabilidade da API; erros constantes em todos os CPFs indicam problema na integração. ### Leia também - [SLA de API de CPF: entenda os níveis de disponibilidade](https://cpfhub.io/blog/sla-api-cpf-niveis-disponibilidade) - [Como lidar com erros comuns ao integrar uma API de consulta de CPF](https://cpfhub.io/blog/como-lidar-com-erros-comuns-ao-integrar-uma-api-de-consulta-de-cpf) - [10 erros mais comuns ao integrar uma API de CPF](https://cpfhub.io/blog/10-erros-mais-comuns-ao-integrar-uma-api-de-cpf) - [Boas práticas para consumir APIs de CPF de forma segura](https://cpfhub.io/blog/boas-praticas-consumir-apis-cpf-segura) --- ## Conclusão Tratar corretamente os códigos de status e mensagens de erro é o que diferencia uma integração amadora de uma integração profissional. Cada código HTTP tem um significado específico e exige uma ação diferente -- retentar, corrigir o formato, verificar a autenticação ou acionar o fallback. A API da [**CPFHub.io**](https://www.cpfhub.io/) Cadastre-se em [cpfhub.io](https://www.cpfhub.io/)