Códigos de Erro

A API segue as convenções REST padrão para códigos de status HTTP. Erros são retornados no formato JSON com um campo error.code para identificação programática.

Estrutura de um erro

JSON

{
  "success": false,
  "error": {
    "code": "CODIGO_DO_ERRO",
    "message": "Descrição legível do erro"
  }
}

Referência completa

2xx - Sucesso

Status	Código	Descrição
`200 OK`	-	Consulta bem-sucedida. O campo `data` contém os resultados.

4xx - Erros do cliente

Status	Código	Descrição
`400 Bad Request`	`INVALID_CPF_FORMAT`	O CPF enviado contém caracteres inválidos ou não está no formato aceito.
`401 Unauthorized`	`MISSING_API_KEY`	O header `x-api-key` está ausente na requisição.
`401 Unauthorized`	`INVALID_API_KEY`	A API Key fornecida não é válida ou foi revogada.
`403 Forbidden`	`SUSPENDED_API_KEY`	A API Key está suspensa. Entre em contato com o suporte.
`403 Forbidden`	`INSUFFICIENT_CREDITS`	Seu plano não possui créditos suficientes para esta consulta.
`404 Not Found`	`CPF_NOT_FOUND`	O CPF não foi encontrado na base de dados. Não consome crédito.
`422 Unprocessable Entity`	`INVALID_CPF_DIGITS`	O CPF possui dígitos verificadores inválidos (falha na validação matemática).
`429 Too Many Requests`	`RATE_LIMIT_EXCEEDED`	O limite de requisições por segundo do seu plano foi excedido.

5xx - Erros do servidor

Status	Código	Descrição
`500 Internal Server Error`	`INTERNAL_ERROR`	Erro interno inesperado. Se persistir, contate o suporte.
`503 Service Unavailable`	`SERVICE_UNAVAILABLE`	API 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
      case 'INSUFFICIENT_CREDITS':
        // Plano sem créditos
        break
      default:
        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 erro	Retry?	Espera
`429`	Sim	Header `Retry-After` ou 1–2s
`500`, `503`	Sim (máx 3x)	1s, 2s, 4s (exponencial)
`400`, `401`, `403`, `404`, `422`	Nã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 12 de maio de 2026