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.

# 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.

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

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

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

# 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

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 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.

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 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 e comece a testar agora.