API de CPF: como tratar respostas de erro (4xx e 5xx) de forma robusta

Ao integrar a API da CPFHub.io, classifique os erros em dois grupos: erros do cliente (4xx), que exigem correção na sua aplicação, e erros do servidor (5xx), que são transitórios e admitem retry com backoff exponencial. O OWASP API Security Top 10 recomenda tratar cada código de status de forma explícita para evitar que falhas silenciosas comprometam a segurança e a rastreabilidade da integração.

Introdução

Toda integração com APIs externas precisa lidar com cenários de erro. Enquanto a resposta de sucesso (HTTP 200) é o caminho feliz, os códigos de erro 4xx e 5xx representam situações que sua aplicação deve tratar de forma específica e informativa. Ignorar ou tratar genericamente esses erros resulta em experiências ruins para o usuário e dificulta a investigação de problemas.

Códigos de resposta da API

A API da CPFHub.io retorna os seguintes códigos de status:

Erros 4xx: problemas no lado do cliente

Os erros 4xx indicam que o problema está na requisição enviada. A correção deve ser feita na sua aplicação.

400 Bad Request

Indica que o CPF enviado tem formato inválido. Causas comuns:

• CPF com menos ou mais de 11 dígitos.
• Caracteres não numéricos na URL (pontos, traços).
• URL mal formatada.

Prevenção: Valide o CPF sintaticamente antes de enviar à API.

401 Unauthorized

A chave de API está ausente, incorreta ou expirada. Causas comuns:

• Header x-api-key não incluído na requisição.
• Chave de API com erro de digitação.
• Chave que foi revogada ou expirou.

Prevenção: Armazene a chave em variável de ambiente e verifique periodicamente sua validade no painel app.cpfhub.io.

404 Not Found

O CPF consultado não foi encontrado na base de dados. Isso não é necessariamente um erro da aplicação — significa que o CPF não possui dados cadastrais associados.

Tratamento: Informe ao usuário que o CPF não foi localizado e permita a inserção manual dos dados, se aplicável.

Erros 5xx: problemas no lado do servidor

Os erros 5xx indicam que algo deu errado no servidor da API. Esses erros são tipicamente transitórios.

500 Internal Server Error

Erro genérico do servidor. Pode ocorrer em momentos de instabilidade.

Tratamento: Retry automático com backoff exponencial. Se persistir após 3 tentativas, acionar fallback.

503 Service Unavailable

O serviço está temporariamente indisponível, geralmente por manutenção programada ou sobrecarga momentânea.

Tratamento: Similar ao 500 — retry com backoff. Em caso de manutenção prolongada, verificar a status page.

Implementação completa em Python

import requests
import time
import random
import logging

logger = logging.getLogger("cpf_api")

class CPFApiError(Exception):
    def __init__(self, codigo, mensagem, retentavel=False):
    self.codigo = codigo
    self.mensagem = mensagem
    self.retentavel = retentavel
    super().__init__(mensagem)

def tratar_resposta(response):
    status = response.status_code

    if status == 200:
    dados = response.json()
    if dados.get("success"):
    return dados
    return dados

    if status == 400:
    raise CPFApiError(400, "CPF com formato inválido", retentavel=False)

    if status == 401:
    raise CPFApiError(401, "Chave de API inválida ou ausente", retentavel=False)

    if status == 404:
    raise CPFApiError(404, "CPF não encontrado na base", retentavel=False)

    if status == 500:
    raise CPFApiError(500, "Erro interno do servidor", retentavel=True)

    if status == 503:
    raise CPFApiError(503, "Serviço temporariamente indisponível", retentavel=True)

    raise CPFApiError(status, f"Erro inesperado: HTTP {status}", retentavel=False)

def consultar_cpf(cpf, max_tentativas=3):
    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):
    try:
    response = requests.get(url, headers=headers, timeout=10)
    return tratar_resposta(response)

    except CPFApiError as e:
    logger.warning(f"Tentativa {tentativa + 1}: {e.mensagem} (HTTP {e.codigo})")

    if not e.retentavel or tentativa == max_tentativas - 1:
    raise

    espera = (2 ** tentativa) + random.uniform(0, 1)
    logger.info(f"Aguardando {espera:.1f}s antes de nova tentativa...")
    time.sleep(espera)

    except requests.exceptions.Timeout:
    logger.warning(f"Tentativa {tentativa + 1}: timeout")

    if tentativa == max_tentativas - 1:
    raise CPFApiError(0, "Timeout após todas as tentativas", retentavel=False)

    espera = (2 ** tentativa) + random.uniform(0, 1)
    time.sleep(espera)

# Uso com tratamento de cada tipo de erro
try:
    resultado = consultar_cpf("12345678900")
    print(f"Sucesso: {resultado}")

except CPFApiError as e:
    if e.codigo == 400:
    print("Verifique o formato do CPF informado.")
    elif e.codigo == 401:
    print("Verifique sua chave de API no painel CPFHub.io.")
    elif e.codigo == 404:
    print("CPF não encontrado. Solicite os dados manualmente.")
    else:
    print(f"Erro: {e.mensagem}")

Implementação completa em JavaScript (Node.js)

class CPFApiError extends Error {
    constructor(codigo, mensagem, retentavel = false) {
    super(mensagem);
    this.codigo = codigo;
    this.retentavel = retentavel;
    }
}

function tratarResposta(response, dados) {
    const status = response.status;

    if (status === 200) return dados;
    if (status === 400) throw new CPFApiError(400, 'CPF com formato inválido');
    if (status === 401) throw new CPFApiError(401, 'API key inválida ou ausente');
    if (status === 404) throw new CPFApiError(404, 'CPF não encontrado');
    if (status === 500) throw new CPFApiError(500, 'Erro interno do servidor', true);
    if (status === 503) throw new CPFApiError(503, 'Serviço indisponível', true);

    throw new CPFApiError(status, `Erro inesperado: HTTP ${status}`);
}

async function consultarCPF(cpf, maxTentativas = 3) {
    const url = `https://api.cpfhub.io/cpf/${cpf}`;

    for (let tentativa = 0; tentativa < maxTentativas; tentativa++) {
    const controller = new AbortController();
    const timeoutId = setTimeout(() => controller.abort(), 10000);

    try {
    const response = await fetch(url, {
    headers: {
    'x-api-key': 'SUA_CHAVE_DE_API',
    'Accept': 'application/json'
    },
    signal: controller.signal
    });

    clearTimeout(timeoutId);
    const dados = await response.json();
    return tratarResposta(response, dados);

    } catch (error) {
    clearTimeout(timeoutId);

    if (error instanceof CPFApiError) {
    if (!error.retentavel || tentativa === maxTentativas - 1) throw error;

    const espera = Math.pow(2, tentativa) * 1000 + Math.random() * 1000;
    await new Promise(r => setTimeout(r, espera));
    continue;
    }

    if (error.name === 'AbortError') {
    if (tentativa === maxTentativas - 1) {
    throw new CPFApiError(0, 'Timeout após todas as tentativas');
    }
    const espera = Math.pow(2, tentativa) * 1000;
    await new Promise(r => setTimeout(r, espera));
    continue;
    }

    throw error;
    }
    }
}

Mensagens de erro para o usuário final

O tratamento de erros deve traduzir códigos HTTP técnicos em mensagens compreensíveis para o usuário:

Note que erros 401 não devem expor detalhes sobre a chave de API ao usuário final — apenas registre internamente.

Perguntas frequentes

A CPFHub.io bloqueia requisições quando o plano é excedido?

Não. A CPFHub.io nunca retorna HTTP 429 nem bloqueia chamadas. Ao ultrapassar a cota do plano, cada consulta adicional é cobrada a R$0,15 e a API continua respondendo normalmente. Não é necessário implementar lógica de backoff por cota — reserve o retry apenas para erros 5xx transitórios.

Quais erros HTTP devo tratar como retentáveis?

Apenas os erros 5xx (500 e 503) são retentáveis, pois indicam falhas transitórias do servidor. Erros 4xx (400, 401, 404) indicam problemas na requisição e não se resolvem com retry — corrija a causa raiz na aplicação antes de tentar novamente.

Como implementar backoff exponencial corretamente?

A estratégia padrão é aguardar 2^tentativa + jitter_aleatório segundos entre cada retry. Para a CPFHub.io, um limite de 3 tentativas com intervalos de 1s, 2s e 4s (mais jitter) é suficiente para cobrir instabilidades transitórias sem atrasar excessivamente o fluxo da aplicação.

O que fazer quando a API retorna HTTP 401 em produção?

Um 401 em produção normalmente indica que a chave de API expirou ou foi revogada. Verifique o painel em app.cpfhub.io, gere uma nova chave se necessário e atualize a variável de ambiente da aplicação. Nunca exponha o detalhe do erro 401 ao usuário final — registre internamente e exiba uma mensagem genérica.

Conclusão

Tratar respostas de erro de forma robusta é o que diferencia uma integração amadora de uma integração profissional. Ao classificar os erros entre retentáveis e não retentáveis, implementar retry inteligente para erros transitórios e traduzir códigos HTTP em mensagens claras para o usuário, sua aplicação se torna mais resiliente e mais fácil de depurar.

Cadastre-se em cpfhub.io — 50 consultas mensais gratuitas, sem cartão de crédito — e implemente tratamento de erros profissional desde a primeira linha de código.