API de CPF: guia prático para debugging de erros de integração

Integrações com APIs externas inevitavelmente apresentam erros -- seja um header ausente, um timeout inesperado ou um formato de dado incorreto. A diferença entre resolver um problema em minutos ou em horas está na abordagem de debugging utilizada. Este guia cobre os erros mais comuns na integração com a API da CPFHub.io -- 401, 400, timeout e 5xx -- com diagnóstico passo a passo e soluções prontas para aplicar.

Metodologia de debugging

Antes de atacar erros específicos, estabeleça uma abordagem estruturada:

1. Isolar o problema

Use cURL para testar a API fora do contexto da sua aplicação. Se funcionar no cURL mas não na aplicação, o problema está no seu código. Se não funcionar no cURL, o problema é de rede, autenticação ou da própria API.

curl -v -X GET "https://api.cpfhub.io/cpf/12345678900" \
    -H "x-api-key: SUA_CHAVE_API" \
    -H "Accept: application/json" \
    --connect-timeout 10 \
    --max-time 30

A flag -v (verbose) mostra os headers de requisição e resposta completos -- informação essencial para o diagnóstico.

2. Verificar camada por camada

Trabalhe de baixo para cima: DNS, conectividade, TLS, autenticação, formato da requisição e, por fim, lógica de negócio.

3. Registrar tudo

Habilite logging detalhado durante o debugging. Em produção, mantenha logs estruturados com request ID, status code e tempo de resposta.

Erro 401 -- Unauthorized

Sintoma

A API retorna status 401 e a mensagem indica que a autenticação falhou.

Causas comuns

• Chave de API ausente: o header x-api-key não foi enviado.
• Chave de API inválida: a chave está incorreta, expirou ou pertence a outra conta.
• Nome do header incorreto: usar Authorization em vez de x-api-key, ou X-Api-Key com capitalização diferente.

Diagnóstico

# Testar com verbose para ver os headers enviados
curl -v -X GET "https://api.cpfhub.io/cpf/12345678900" \
    -H "x-api-key: SUA_CHAVE_API" \
    -H "Accept: application/json" \
    --connect-timeout 10 \
    --max-time 30 2>&1 | grep -i "x-api-key"

Solução

Verifique se o header está exatamente como x-api-key (tudo em minúsculas) e se o valor corresponde à chave gerada no painel da CPFHub.io

# Correto
headers = {
    "x-api-key": "sk_live_abc123...",
    "Accept": "application/json"
}

# Errado -- nome do header incorreto
headers = {
    "Authorization": "Bearer sk_live_abc123...",
    "Accept": "application/json"
}

Erro 400 -- Bad Request

Sintoma

A API retorna status 400, indicando que a requisição está malformada.

Causas comuns

• CPF com formatação: enviar 123.456.789-00 em vez de 12345678900.
• CPF com tamanho incorreto: menos ou mais de 11 dígitos.
• Caracteres não numéricos: espaços, letras ou caracteres especiais no CPF.

Diagnóstico

Verifique o valor exato que está sendo enviado na URL:

import re

def limpar_cpf(cpf: str) -> str:
    """Remove formatação do CPF, mantendo apenas dígitos."""
    cpf_limpo = re.sub(r"\D", "", cpf)

    if len(cpf_limpo) != 11:
    raise ValueError(f"CPF deve ter 11 digitos, recebeu {len(cpf_limpo)}")

    return cpf_limpo

# Testes
print(limpar_cpf("123.456.789-00")) # "12345678900"
print(limpar_cpf("12345678900")) # "12345678900"
print(limpar_cpf("1234567890")) # ValueError

Solução

Sempre sanitize o CPF antes de enviar à API. Remova pontos, traços e espaços, e valide que o resultado tem exatamente 11 dígitos.

Erro de Timeout

Sintoma

A requisição nunca retorna ou lança uma exceção de timeout.

Causas comuns

• Timeout muito baixo: configurar timeout de 1-2 segundos quando a API tem latência média de ~900 ms.
• Problemas de rede: firewall bloqueando a saída, DNS lento ou instabilidade na conexão.
• Proxy ou VPN interferindo: proxies corporativos podem adicionar latência ou bloquear conexões.

Diagnóstico

# Testar resolução DNS
nslookup api.cpfhub.io

# Testar conectividade
curl -o /dev/null -s -w "DNS: %{time_namelookup}s\nConexao: %{time_connect}s\nTLS: %{time_appconnect}s\nTotal: %{time_total}s\n" \
    "https://api.cpfhub.io/cpf/12345678900" \
    -H "x-api-key: SUA_CHAVE_API" \
    -H "Accept: application/json" \
    --connect-timeout 10 \
    --max-time 30

Solução

Configure timeouts adequados -- recomendamos 30 segundos para o timeout total e 10 segundos para o timeout de conexão:

import requests

response = requests.get(
    "https://api.cpfhub.io/cpf/12345678900",
    headers={
    "x-api-key": "SUA_CHAVE_API",
    "Accept": "application/json"
    },
    timeout=(10, 30) # (connect_timeout, read_timeout)
)

Cota esgotada -- comportamento da API

O que acontece ao atingir o limite

A CPFHub.io não bloqueia as requisições quando a cota mensal é atingida. Em vez disso, cada consulta extra é cobrada a R$0,15 -- o serviço permanece disponível sem interrupção. O plano Gratuito inclui 50 consultas/mês e o plano Pro inclui 1.000 consultas/mês por R$149.

Diagnóstico

Acompanhe o consumo pelo painel em app.cpfhub.io/settings/billing ou implemente contadores no lado do cliente para projetar o consumo mensal antes de atingir o limite.

Solução

Implemente controle de volume no lado do cliente e considere um upgrade de plano se o volume crescer consistentemente acima da cota incluída.

import time

def consultar_com_rate_limit(cliente, cpfs, intervalo=1.0):
    """Consulta lista de CPFs com intervalo entre requisições."""
    resultados = []
    for cpf in cpfs:
    resultado = cliente.consultar(cpf)
    resultados.append(resultado)
    time.sleep(intervalo)
    return resultados

Erro 500 -- Internal Server Error

Sintoma

A API retorna status 500 ou 502/503/504.

Causas comuns

Erros 5xx indicam problemas do lado do servidor. Com o SLA de 99,9% da CPFHub.io

Solução

Implemente retry com backoff exponencial para erros 5xx. A recomendação do OWASP para integrações resilientes é nunca fazer retry imediato -- espaçe as tentativas com espera crescente:

import time
import requests

def consultar_com_retry(cpf, api_key, max_retries=3):
    """Consulta CPF com retry para erros de servidor."""
    for tentativa in range(max_retries):
    try:
    response = requests.get(
    f"https://api.cpfhub.io/cpf/{cpf}",
    headers={
    "x-api-key": api_key,
    "Accept": "application/json"
    },
    timeout=30
    )

    if response.status_code < 500:
    return response.json()

    wait_time = (2 ** tentativa) + 0.5
    print(f"Erro {response.status_code}. Tentando novamente em {wait_time}s...")
    time.sleep(wait_time)

    except requests.exceptions.Timeout:
    wait_time = (2 ** tentativa) + 0.5
    print(f"Timeout. Tentando novamente em {wait_time}s...")
    time.sleep(wait_time)

    return {"success": False, "error": "max_retries_exceeded"}

Resposta com corpo vazio ou inesperado

Sintoma

A requisição retorna status 200, mas o corpo está vazio ou em formato inesperado.

Causas comuns

• Header Accept ausente: sem Accept: application/json, a resposta pode vir em outro formato.
• Parsing incorreto: tentar fazer parse de texto como JSON.

Solução

Sempre inclua o header Accept: application/json e valide o formato da resposta antes de processá-la:

response = requests.get(
    f"https://api.cpfhub.io/cpf/{cpf}",
    headers={
    "x-api-key": api_key,
    "Accept": "application/json"
    },
    timeout=30
)

content_type = response.headers.get("Content-Type", "")
if "application/json" not in content_type:
    print(f"Formato inesperado: {content_type}")
    print(f"Corpo: {response.text[:200]}")
else:
    dados = response.json()

Checklist de debugging

Quando um erro aparecer, siga esta lista ordenada:

1. Reproduzir o erro com cURL verbose.
2. Verificar o status code HTTP.
3. Verificar os headers de requisição (especialmente x-api-key e Accept).
4. Verificar o formato do CPF na URL (11 dígitos, apenas números).
5. Verificar conectividade de rede (DNS, firewall, proxy).
6. Verificar os logs do lado do cliente.
7. Verificar o consumo do plano no painel da CPFHub.io.
8. Testar a partir de outra rede ou máquina para isolar problemas locais.

Perguntas frequentes

Qual é a latência esperada da API de CPF da CPFHub.io?

A latência média da API da CPFHub.io é de aproximadamente 900ms. Configure o timeout da sua requisição em pelo menos 30 segundos (10s para conexão, 30s para leitura) para evitar falsos timeouts. Valores abaixo de 2 segundos são muito restritivos para consultas à Receita Federal.

O que acontece quando a cota mensal do plano Gratuito é atingida?

A API não bloqueia as requisições. Cada consulta além das 50 incluídas no plano Gratuito é cobrada a R$0,15 automaticamente. O plano Pro inclui 1.000 consultas por R$149/mês, com o mesmo modelo de cobrança por excedente sem interrupção de serviço.

Como garantir conformidade com a LGPD ao usar uma API de CPF?

Use o CPF apenas para a finalidade declarada ao titular, armazene apenas o necessário (não guarde o CPF cru se um token bastar), implemente controle de acesso aos logs de consulta e documente a base legal para o tratamento. A ANPD orienta que dados de identificação devem ser tratados com o princípio da necessidade.

Quanto tempo leva para integrar a API CPFHub.io?

A integração básica leva menos de 30 minutos: crie uma conta em cpfhub.io, gere a API key no painel e faça uma chamada GET para https://api.cpfhub.io/cpf/{CPF} com o header x-api-key. A documentação inclui exemplos em Python, Node.js, PHP, Java e outras linguagens.

Conclusão

Debugging de integrações com API não precisa ser um processo doloroso. Com uma abordagem sistemática -- isolar, diagnosticar camada por camada e aplicar a correção específica -- a maioria dos erros é resolvida em minutos. Os problemas mais comuns (401, 400, timeout) têm soluções diretas que envolvem verificar headers, sanitizar inputs e configurar timeouts adequados para a latência real de ~900ms da API.

A CPFHub.io

Cadastre-se em cpfhub.io