CPFHub.io

Códigos de Erro

A API segue as convenções REST padrão para códigos de status HTTP. Use o status HTTP para decidir o que fazer e a mensagem apenas para log ou exibição.

Estrutura de um erro

Existem dois formatos. A maioria dos erros traz error como objeto com message:

[object Object]

Erros de autenticação e de conta trazem error como string: 401, 403 de conta inativa ou bloqueada, 500 "Erro ao validar assinatura" e 503 "usage_unavailable". O 403 de créditos na Consulta Simples e na Consulta em Tempo Real vem como objeto.

JSON
{
  "success": false,
  "error": "API Key não fornecida"
}

Para ler a mensagem nos dois casos: typeof body.error === 'string' ? body.error : body.error?.message.

ℹ

Use o status HTTP

Decida o tratamento pelo status HTTP. As mensagens estão em português e servem para log e exibição: não compare o texto no seu código.

Referência completa

2xx: Sucesso

StatusMensagemDescrição
200 OKNenhumaConsulta bem-sucedida. O campo data contém os resultados.
202 AcceptedNenhumaSó na consulta em lote: lote aceito para processamento.

4xx: Erros do cliente

StatusMensagemDescrição
400 Bad RequestCPF inválido. Deve conter 11 dígitos.O CPF não tem 11 dígitos depois de remover a formatação.
400 Bad RequestData de nascimento inválida. Use o formato DD/MM/YYYY ou DDMMYYYYSó na Consulta em Tempo Real: birthDate ausente ou inválido.
400 Bad RequestCampo 'cpfs' deve ser um array não vazio.Só na consulta em lote: cpfs ausente, vazio ou não é array.
400 Bad RequestLimite de 10000 CPFs por lote excedido.Só na consulta em lote: mais de 10.000 CPFs.
400 Bad RequestCNPJ inválido. Formato ou dígito verificador incorreto.Só na Consulta de CNPJ: formato errado ou dígito verificador incorreto. Não consome crédito.
400 Bad RequestCampo 'cnpjs' deve ser um array não vazio. ou Limite de 10000 CNPJs por lote excedido.Só na consulta de CNPJ em lote: cnpjs ausente, vazio, não é array ou tem mais de 10.000 itens.
401 UnauthorizedAPI Key não fornecidaO header x-api-key está ausente. error é string.
401 UnauthorizedAPI Key inválidaA API Key não existe. error é string.
401 UnauthorizedAPI Key inativaA API Key foi substituída por uma nova no dashboard. error é string.
403 ForbiddenLimite de créditos excedidoSaldo menor que o custo da consulta, em planos sem excedente. Na Consulta Simples e na Consulta em Tempo Real, error é objeto. Na Consulta de CNPJ, em geral é string: leia os dois formatos.
403 ForbiddenCréditos insuficientes para o lote: N necessários.Só no envio de lote de CPF: o saldo não cobre todos os CPFs válidos da lista, inclusive com saldo zerado, em planos sem excedente.
403 ForbiddenCréditos insuficientes para o lote.Só no envio de lote de CNPJ: o saldo não cobre todos os CNPJs válidos da lista, inclusive com saldo zerado, em planos sem excedente.
403 ForbiddenUsuário inativo. Entre em contato com o suporte.Conta desativada. error é string.
403 ForbiddenConta bloqueada. Entre em contato com o suporte.Conta bloqueada. error é string.
404 Not FoundCPF não encontrado na base de dadosSó na Consulta Simples. Não consome crédito.
404 Not FoundCNPJ não encontrado na base de dadosSó na Consulta de CNPJ. Não consome crédito.
404 Not FoundLote não encontrado.Só no status do lote (CPF ou CNPJ): jobId não existe ou foi criado com outra API Key. Uma falha ao ler o lote responde 503, não 404.
422 Unprocessable EntityCPF inválido. Dígito verificador incorreto.O CPF falhou na validação matemática dos dígitos verificadores.
422 Unprocessable EntityNenhum CPF válido na lista enviada.Só na consulta em lote: nenhum item da lista é um CPF válido.
422 Unprocessable EntityNenhum CNPJ válido na lista enviada.Só na consulta de CNPJ em lote: nenhum item da lista é um CNPJ válido.
422 Unprocessable EntityMensagem da Receita FederalSó na Consulta em Tempo Real: a Receita recusou a consulta, por exemplo por data de nascimento divergente. Não consome crédito.
429 Too Many RequestsLimite de requisições por minuto excedido. Tente novamente em N segundos.Passou do limite por minuto da Consulta Simples, da Consulta em Tempo Real, da Consulta de CNPJ (que divide o limite da Consulta Simples) ou do envio de lote. Traz o header Retry-After. Não consome crédito.
429 Too Many RequestsLimite de N lotes pendentes por cliente excedido.Só no envio de lote de CNPJ: há lotes demais em processamento. Traz Retry-After: 60. Deixe os lotes anteriores terminarem.
429 Too Many RequestsEste CPF foi consultado repetidas vezes em sequência pela mesma chave. Novas consultas dele estão bloqueadas temporariamente para não consumir seus créditos. Verifique se sua integração está em loop. As consultas de outros CPFs seguem normais.Proteção contra consultas repetidas: o mesmo CPF foi consultado 20 vezes em 10 minutos pela mesma chave. Só na Consulta Simples (GET /cpf/{cpf}); não vale para Tempo Real, CNPJ nem lote. O bloqueio é temporário. Não consome crédito.

Uma rota que não existe responde 404 com o texto puro NOT_FOUND, sem JSON. Confira o Content-Type antes de ler o corpo como JSON.

5xx: Erros do servidor

StatusMensagemDescrição
500 Internal Server ErrorErro ao validar assinaturaFalha interna ao ler o seu plano. error é string.
500 Internal Server ErrorBanco de dados indisponívelFalha interna na Consulta Simples.
500 Internal Server ErrorFalha ao criar lote.Só no envio de lote (CPF ou CNPJ): o lote não pôde ser criado.
502 Bad GatewayFalha ao interpretar a resposta da Receita Federal.Só na Consulta em Tempo Real. Não consome crédito.
502 / 503A Receita Federal não respondeu a tempo. Tente novamente em alguns segundos. Nenhum crédito foi cobrado.Só na Consulta em Tempo Real. Não consome crédito.
502 / 503A Receita Federal está com alta demanda agora. Tente novamente em alguns segundos. Nenhum crédito foi cobrado.Só na Consulta em Tempo Real. Não consome crédito.
503 Service UnavailableNão foi possível reservar os créditos. Tente novamente.Falha interna ao reservar os créditos da consulta. Não consome crédito.
503 Service UnavailableFalha ao registrar validaçãoFalha interna ao gravar a consulta. Não consome crédito.
503 Service Unavailablecnpj_unavailableSó na Consulta de CNPJ: a base de CNPJ está indisponível no momento. Não consome crédito. Repita com espera crescente.
503 Service Unavailableusage_unavailableNão foi possível verificar o saldo de créditos. Não consome crédito.
503 Service UnavailableNão foi possível ler os resultados do lote agora. Tente novamente.Só no status do lote (CPF ou CNPJ) e no get_bulk_job do MCP, com error.code bulk_results_unavailable. O lote continua existindo: não reenvie, repita o mesmo GET com espera crescente. Não consome crédito.

O 503 de saldo indisponível traz error como string e um campo message:

JSON
{
  "success": false,
  "error": "usage_unavailable",
  "message": "Não foi possível verificar o saldo de créditos. Tente novamente."
}

Exemplo de tratamento de erros

TypeScript
const res = await fetch(`https://api.cpfhub.io/cpf/${cpf}`, {
  headers: { 'x-api-key': process.env.CPFHUB_API_KEY! },
  signal: AbortSignal.timeout(10_000),
})
const isJson = res.headers.get('content-type')?.includes('application/json')
const body = isJson ? await res.json() : null

if (res.ok) {
  console.log(body.data.name)
} else {
  // error é string em alguns erros e objeto { message } nos demais
  const message = typeof body?.error === 'string' ? body.error : body?.error?.message

  switch (res.status) {
    case 404:
      // CPF não encontrado: não consome crédito
      break
    case 400:
    case 422:
      // Entrada inválida: corrija, não repita
      break
    case 401:
    case 403:
      // Chave inválida, créditos esgotados ou conta bloqueada: não repita
      throw new Error(message)
    case 429:
      // Limite por minuto: espere Retry-After segundos e repita
      await new Promise(r => setTimeout(r, Number(res.headers.get('retry-after') ?? 5) * 1000))
      break
    default:
      // 5xx: repita com backoff (veja a tabela abaixo)
      throw new Error(message ?? `HTTP ${res.status}`)
  }
}
Python
import os, time, requests

res = requests.get(
    f"https://api.cpfhub.io/cpf/{cpf}",
    headers={"x-api-key": os.environ["CPFHUB_API_KEY"]},
    timeout=10,
)
is_json = "application/json" in res.headers.get("content-type", "")
body = res.json() if is_json else {}

if res.ok:
    print(body["data"]["name"])
else:
    error = body.get("error")
    message = error if isinstance(error, str) else (error or {}).get("message")

    if res.status_code == 404:
        print("CPF não encontrado")
    elif res.status_code == 429:
        time.sleep(int(res.headers.get("retry-after", "5")))  # depois repita
    elif res.status_code >= 500:
        pass  # repita com backoff
    else:
        raise RuntimeError(message)

Retentativas

StatusRepetir?Como
429SimEspere o valor do header Retry-After
500, 502, 503 em GET (Consulta Simples, status do lote, saldo)Sim, até 3 vezesBackoff: 1 s, 2 s, 4 s
502, 503 recebidos no POST /cpf/realtimeSim, até 3 vezesBackoff: 2 s, 4 s, 8 s
400, 401, 403, 404, 422NãoCorrija a entrada, a chave ou o saldo
⚠

POST não é idempotente

POST /cpf/realtime e POST /cpf/bulk não aceitam chave de idempotência. Se a conexão cair ou o seu timeout estourar antes da resposta, a consulta pode ter sido concluída e cobrada, ou o lote pode ter sido criado. Antes de repetir, confira o saldo em GET /quota e, no lote, os envios recentes no dashboard. Repita sem conferir só quando tiver recebido 429, 502 ou 503.

Testando sem gastar créditos

Não consomem crédito: 400, 401, 404, 422 e 429. Dá para testar o tratamento de erros de graça:

TesteRequisiçãoResposta
CPF com menos de 11 dígitosGET /cpf/123400
Dígito verificador inválidoGET /cpf/11111111111422
Data de nascimento inválidaPOST /cpf/realtime com {"cpf":"12345678909","birthDate":"1990-06"}400
Sem API Keyqualquer rota, sem o header x-api-key401
Saldo da contaGET /quota200, sempre grátis
  • Uma resposta 200 consome crédito. O plano Grátis tem 50 créditos para testar o caminho de sucesso.
  • O CPF 12345678909 dos exemplos é fictício. Para testar o sucesso, use um CPF cujo titular autorizou a consulta.

Atualizado em 15 de outubro de 2026