CPFHub.io
Começar grátis

Códigos de Erro

A API segue as convenções REST padrão para códigos de status HTTP.

Estrutura de um erro

Erros de autenticação (401) retornam error como string, não como objeto:

JSON
{
  "success": false,
  "error": "API Key não fornecida"
}
JSON
{
  "success": false,
  "error": "API Key inválida"
}
⚠

401 e 403 de crédito não usam error.code

Chaves ausentes ou inválidas não devolvem { code, message }. O campo error é a string acima, em GET /cpf/{cpf}, GET /quota e no endpoint de lote.

Créditos esgotados sem overage (Grátis, ou pago com overage desligado) também devolvem error como string: "Limite de créditos excedido". Planos com overage ativo não retornam 403 de crédito.

JSON
{
  "success": false,
  "error": "Limite de créditos excedido"
}

Referência completa

2xx - Sucesso

StatusCódigoDescrição
200 OK-Consulta bem-sucedida. O campo data contém os resultados.

4xx - Erros do cliente

StatusCódigoDescrição
400 Bad RequestINVALID_CPF_FORMATO CPF enviado contém caracteres inválidos ou não está no formato aceito.
401 Unauthorized— (string "API Key não fornecida")O header x-api-key está ausente. error é uma string, não um objeto.
401 Unauthorized— (string "API Key inválida")A API Key fornecida não é válida. error é uma string, não um objeto.
403 ForbiddenSUSPENDED_API_KEYA API Key está suspensa. Entre em contato com o suporte.
403 Forbidden— (string "Limite de créditos excedido")Créditos esgotados sem overage (Grátis ou pago com overage desligado). Planos com overage ativo não retornam 403 de crédito.
404 Not FoundCPF_NOT_FOUNDO CPF não foi encontrado na base de dados. Não consome crédito.
422 Unprocessable EntityINVALID_CPF_DIGITSO CPF possui dígitos verificadores inválidos (falha na validação matemática).
429 Too Many RequestsRATE_LIMIT_EXCEEDEDO limite de requisições por segundo do seu plano foi excedido.

5xx - Erros do servidor

StatusCódigoDescrição
500 Internal Server ErrorINTERNAL_ERRORErro interno inesperado. Se persistir, contate o suporte.
503 Service UnavailableSERVICE_UNAVAILABLEAPI temporariamente indisponível. Tente novamente em alguns instantes.

Exemplo de tratamento de erros

TypeScript
import { CPFHub, CPFHubError } from '@cpfhub/sdk'

const client = new CPFHub({ apiKey: process.env.CPFHUB_API_KEY })

try {
  const result = await client.lookup('12345678909')
  console.log(result.data.name)
} catch (err) {
  if (err instanceof CPFHubError) {
    switch (err.code) {
      case 'CPF_NOT_FOUND':
        // CPF não existe - não consome crédito
        break
      case 'INVALID_CPF_DIGITS':
        // CPF matematicamente inválido
        break
      case 'RATE_LIMIT_EXCEEDED':
        // Aguarde e tente novamente
        await sleep(1000)
        break
      default:
        // 403 de crédito: body live `{"success":false,"error":"Limite de créditos excedido"}`
        if (err.message === 'Limite de créditos excedido') break
        throw err
    }
  }
}
Python
from cpfhub import CPFHub, CPFHubError
import os

client = CPFHub(api_key=os.environ["CPFHUB_API_KEY"])

try:
    result = client.lookup("12345678909")
    print(result.data.name)
except CPFHubError as e:
    if e.code == "CPF_NOT_FOUND":
        print("CPF não encontrado")
    elif e.code == "RATE_LIMIT_EXCEEDED":
        import time; time.sleep(1)
    else:
        raise

Retry e resiliência

✦

Boas práticas para produção

Para ambientes de produção, implemente retry com backoff exponencial para erros 5xx e 429. Erros 4xx (exceto 429) geralmente não se resolvem com retry.

Sugestão de estratégia:

Tipo de erroRetry?Espera
429SimHeader Retry-After ou 1–2s
500, 503Sim (máx 3x)1s, 2s, 4s (exponencial)
400, 401, 403, 404, 422Não-

Header Retry-After

Em respostas 429, a API inclui o header Retry-After com o número de segundos para aguardar:

HTTP/1.1 429 Too Many Requests
Retry-After: 2

Atualizado em 5 de setembro de 2026