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

> Guia completo para identificar e resolver erros comuns na integração com API de CPF. Códigos HTTP, timeouts, headers e mais.

**Publicado:** 15/08/2026
**Autor:** Redação CPFHub.io
**URL:** https://cpfhub.io/blog/api-cpf-guia-pratico-debugging-erros-integracao

---


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.

```bash
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

```bash
# 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**](https://www.cpfhub.io/)

```python
# 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:

```python
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

```bash
# 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:

```python
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](https://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.

```python
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**](https://www.cpfhub.io/)

### Solução

Implemente retry com backoff exponencial para erros 5xx. A recomendação do [OWASP](https://owasp.org/www-community/controls/Blocking_Brute_Force_Attacks) para integrações resilientes é nunca fazer retry imediato -- espaçe as tentativas com espera crescente:

```python
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:

```python
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](https://www.gov.br/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.

### Leia também

- [SLA de API de CPF: entenda os níveis de disponibilidade](https://cpfhub.io/blog/sla-api-cpf-niveis-disponibilidade)
- [Como implementar retry com backoff exponencial em consultas de API de CPF](https://cpfhub.io/blog/como-implementar-retry-backoff-exponencial-consultas-api-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

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**](https://www.cpfhub.io/)

Cadastre-se em [cpfhub.io](https://www.cpfhub.io/)