API de CPF: guia completo de códigos 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 é ú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.

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

{
    "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

{
    "success": false
}

Tratamento

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

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

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

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

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

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.

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

Cadastre-se em cpfhub.io