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.
{
"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
| Status | Mensagem | Descrição |
|---|---|---|
200 OK | Nenhuma | Consulta bem-sucedida. O campo data contém os resultados. |
202 Accepted | Nenhuma | Só na consulta em lote: lote aceito para processamento. |
4xx: Erros do cliente
| Status | Mensagem | Descrição |
|---|---|---|
400 Bad Request | CPF inválido. Deve conter 11 dígitos. | O CPF não tem 11 dígitos depois de remover a formatação. |
400 Bad Request | Data de nascimento inválida. Use o formato DD/MM/YYYY ou DDMMYYYY | Só na Consulta em Tempo Real: birthDate ausente ou inválido. |
400 Bad Request | Campo 'cpfs' deve ser um array não vazio. | Só na consulta em lote: cpfs ausente, vazio ou não é array. |
400 Bad Request | Limite de 10000 CPFs por lote excedido. | Só na consulta em lote: mais de 10.000 CPFs. |
400 Bad Request | CNPJ 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 Request | Campo '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 Unauthorized | API Key não fornecida | O header x-api-key está ausente. error é string. |
401 Unauthorized | API Key inválida | A API Key não existe. error é string. |
401 Unauthorized | API Key inativa | A API Key foi substituída por uma nova no dashboard. error é string. |
403 Forbidden | Limite de créditos excedido | Saldo 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 Forbidden | Cré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 Forbidden | Cré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 Forbidden | Usuário inativo. Entre em contato com o suporte. | Conta desativada. error é string. |
403 Forbidden | Conta bloqueada. Entre em contato com o suporte. | Conta bloqueada. error é string. |
404 Not Found | CPF não encontrado na base de dados | Só na Consulta Simples. Não consome crédito. |
404 Not Found | CNPJ não encontrado na base de dados | Só na Consulta de CNPJ. Não consome crédito. |
404 Not Found | Lote 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 Entity | CPF inválido. Dígito verificador incorreto. | O CPF falhou na validação matemática dos dígitos verificadores. |
422 Unprocessable Entity | Nenhum CPF válido na lista enviada. | Só na consulta em lote: nenhum item da lista é um CPF válido. |
422 Unprocessable Entity | Nenhum CNPJ válido na lista enviada. | Só na consulta de CNPJ em lote: nenhum item da lista é um CNPJ válido. |
422 Unprocessable Entity | Mensagem da Receita Federal | Só 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 Requests | Limite 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 Requests | Limite 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 Requests | Este 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
| Status | Mensagem | Descrição |
|---|---|---|
500 Internal Server Error | Erro ao validar assinatura | Falha interna ao ler o seu plano. error é string. |
500 Internal Server Error | Banco de dados indisponível | Falha interna na Consulta Simples. |
500 Internal Server Error | Falha ao criar lote. | Só no envio de lote (CPF ou CNPJ): o lote não pôde ser criado. |
502 Bad Gateway | Falha ao interpretar a resposta da Receita Federal. | Só na Consulta em Tempo Real. Não consome crédito. |
502 / 503 | A 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 / 503 | A 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 Unavailable | Nã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 Unavailable | Falha ao registrar validação | Falha interna ao gravar a consulta. Não consome crédito. |
503 Service Unavailable | cnpj_unavailable | Só na Consulta de CNPJ: a base de CNPJ está indisponível no momento. Não consome crédito. Repita com espera crescente. |
503 Service Unavailable | usage_unavailable | Não foi possível verificar o saldo de créditos. Não consome crédito. |
503 Service Unavailable | Nã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:
{
"success": false,
"error": "usage_unavailable",
"message": "Não foi possível verificar o saldo de créditos. Tente novamente."
}Exemplo de tratamento de erros
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}`)
}
}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
| Status | Repetir? | Como |
|---|---|---|
429 | Sim | Espere o valor do header Retry-After |
500, 502, 503 em GET (Consulta Simples, status do lote, saldo) | Sim, até 3 vezes | Backoff: 1 s, 2 s, 4 s |
502, 503 recebidos no POST /cpf/realtime | Sim, até 3 vezes | Backoff: 2 s, 4 s, 8 s |
400, 401, 403, 404, 422 | Não | Corrija 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:
| Teste | Requisição | Resposta |
|---|---|---|
| CPF com menos de 11 dígitos | GET /cpf/123 | 400 |
| Dígito verificador inválido | GET /cpf/11111111111 | 422 |
| Data de nascimento inválida | POST /cpf/realtime com {"cpf":"12345678909","birthDate":"1990-06"} | 400 |
| Sem API Key | qualquer rota, sem o header x-api-key | 401 |
| Saldo da conta | GET /quota | 200, sempre grátis |
- Uma resposta
200consome crédito. O plano Grátis tem 50 créditos para testar o caminho de sucesso. - O CPF
12345678909dos exemplos é fictício. Para testar o sucesso, use um CPF cujo titular autorizou a consulta.
Atualizado em 15 de outubro de 2026