Limites de Uso
A API CPFHub.io tem dois limites:
- Créditos: cada consulta bem-sucedida consome créditos da franquia do seu plano.
- Requisições por minuto: um teto de chamadas por minuto em cada tipo de consulta, para proteger a estabilidade da API.
Os custos abaixo são os padrões. Consulte os custos e as regras de excedente específicos do seu plano no dashboard. Os limites padrão são 30/min na Consulta Simples (cada envio de lote conta como 1) e 5/min na Consulta em Tempo Real. Planos personalizados podem ter limites diferentes; confirme com o suporte da CPFHub.io. Acima do limite, a API responde 429 com o header Retry-After. O saldo e o plano atual aparecem em GET /quota, que não consome crédito.
Créditos por plano
| Plano no site | Nome em GET /quota | Créditos por período | Ao esgotar |
|---|---|---|---|
| Grátis | Grátis | 50 | A API para e responde 403 até a renovação |
| Pro | Micro | 100 | Continua consultando; o excedente é cobrado na fatura seguinte |
| Pro | Básico | 1.000 | Continua consultando; o excedente é cobrado na fatura seguinte |
| Pro | Intermediário | 5.000 | Continua consultando; o excedente é cobrado na fatura seguinte |
| Pro | Avançado | 10.000 | Continua consultando; o excedente é cobrado na fatura seguinte |
| Corporativo | Plano personalizado | Sob consulta | Negociado |
O plano Pro do site é um seletor de volume: cada volume corresponde a um dos planos acima. Planos personalizados podem ter regras próprias; confira as condições da sua conta no dashboard. Veja preços em cpfhub.io/precos.
Quando os créditos renovam: nos planos pagos, no início de cada ciclo de cobrança da assinatura. No plano Grátis, no dia 1º de cada mês (UTC). O saldo é da conta inteira, somando todas as chaves.
Custo por consulta
| Consulta | Custo |
|---|---|
Consulta Simples (GET /cpf/{cpf}) | 1 crédito por CPF encontrado |
Consulta em Tempo Real (POST /cpf/realtime) | 1,5 crédito por consulta bem-sucedida |
Consulta em lote (POST /cpf/bulk) | 1 crédito por CPF encontrado |
Status do lote (GET /cpf/bulk/{jobId}) | Grátis |
Consulta de CNPJ (GET /cnpj/{cnpj}) | 1 crédito por CNPJ encontrado |
Consulta de CNPJ em lote (POST /cnpj/bulk) | 1 crédito por CNPJ encontrado |
Status do lote de CNPJ (GET /cnpj/bulk/{jobId}) | Grátis |
| Verificação de Identidade (KYC) | 5 créditos por verificação concluída (aprovada, reprovada ou em revisão manual). Falha técnica não cobra; criar ou consultar o link é grátis |
Saldo de créditos (GET /quota) | Grátis |
Esses são os custos padrão. Consulte os custos específicos do seu plano no dashboard.
Erros não consomem crédito
CPF ou CNPJ não encontrado (404), CPF ou CNPJ com formato inválido (400/422), limite por minuto (429) e falhas na consulta à Receita Federal (422/502/503) não consomem créditos.
Créditos esgotados
Em planos sem cobrança de excedente, como o Grátis, a API responde 403 quando o saldo não cobre o custo da consulta:
| Onde | Mensagem | Formato de error |
|---|---|---|
| Consulta Simples e Consulta em Tempo Real | Limite de créditos excedido | Objeto (error.message) |
| Envio de lote de CPF, saldo menor que a lista ou zerado | Créditos insuficientes para o lote: N necessários. | Objeto (error.message) |
| Envio de lote de CNPJ, saldo menor que a lista ou zerado | Créditos insuficientes para o lote. | Objeto (error.message) |
| Consulta de CNPJ | Limite de créditos excedido | Em geral string. Leia os dois formatos. |
- A Consulta de CNPJ usa a mesma franquia e o mesmo custo da Consulta Simples.
- No lote (de CPF ou de CNPJ), o saldo precisa cobrir todos os documentos válidos da lista antes do envio. Se não cobrir, nada é cobrado.
- Um saldo de 1 crédito ainda permite uma Consulta Simples, mas não uma Consulta em Tempo Real (1,5 crédito).
- Acompanhe o saldo em
GET /quota, que funciona com créditos zerados e não consome crédito.
Limite por minuto
| Consulta | Limite padrão |
|---|---|
Consulta Simples (GET /cpf/{cpf}) | 30 requisições por minuto |
Consulta de CNPJ (GET /cnpj/{cnpj}) | Divide as 30 requisições por minuto da Consulta Simples |
Consulta em lote (POST /cpf/bulk) | Cada envio conta como 1 requisição da Consulta Simples |
Consulta em Tempo Real (POST /cpf/realtime) | 5 requisições por minuto |
Esses são os limites padrão. Planos personalizados podem ter limites diferentes; confirme com o suporte da CPFHub.io. Cada envio de lote conta como uma requisição da Consulta Simples. Acima do limite, a API responde 429 com o header Retry-After.
- O limite vale por API Key e por tipo de consulta. A Consulta Simples de CPF e a Consulta de CNPJ são o mesmo tipo: 20 CPFs e 10 CNPJs no mesmo minuto já somam 30.
- Toda requisição conta, inclusive as que respondem
404. - A contagem zera no início de cada minuto do relógio.
GET /cpf/bulk/{jobId}eGET /quotanão entram no limite.
Ao passar do limite, a API responde 429 com o header Retry-After (segundos até liberar) e não consome crédito:
HTTP/1.1 429 Too Many Requests
Retry-After: 18{
"success": false,
"data": null,
"error": {
"message": "Limite de requisições por minuto excedido. Tente novamente em 18 segundos."
}
}Espere o tempo de Retry-After e repita a mesma requisição. Para muitos CPFs, use a consulta em lote: um único envio processa até 10.000 CPFs e conta como uma requisição.
Proteção contra consultas repetidas
Só na Consulta Simples (GET /cpf/{cpf}): se a mesma chave consultar o mesmo CPF 20 vezes em 10 minutos, novas consultas desse CPF são bloqueadas temporariamente com 429 (mensagem "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."). A proteção não se aplica à Consulta em Tempo Real, à Consulta de CNPJ nem às consultas em lote. Se você precisa reutilizar o resultado de um CPF, guarde-o no seu sistema em vez de consultar de novo.
Limite por IP nos endpoints públicos do KYC
Os endpoints públicos usados pelo token do link de Verificação de Identidade também têm um limite por IP. Acima dele, a API responde 429.
Limite por lote
POST /cpf/bulk aceita até 10.000 CPFs por requisição. Para volumes maiores, divida em várias chamadas. Detalhes em Consulta em Lote.
POST /cnpj/bulk aceita até 10.000 CNPJs por requisição e tem um limite de lotes pendentes por cliente (acima dele, 429 com Retry-After: 60). Detalhes em Consulta de CNPJ em Lote.
A Consulta em Tempo Real não está disponível em lote.
Uso em volume
Use o endpoint de lote para grandes volumes
Para muitos CPFs de uma vez, prefira POST /cpf/bulk: uma chamada processa até 10.000 CPFs em segundo plano.
Se preferir chamadas individuais, limite a concorrência e respeite o 429:
import asyncio, os
import httpx
CONCORRENCIA = 5
async def process_batch(cpf_list: list[str]):
semaphore = asyncio.Semaphore(CONCORRENCIA)
async with httpx.AsyncClient(
base_url='https://api.cpfhub.io',
headers={'x-api-key': os.environ['CPFHUB_API_KEY']},
timeout=10,
) as client:
async def lookup_one(cpf: str):
async with semaphore:
for _ in range(3):
res = await client.get(f'/cpf/{cpf}')
if res.status_code != 429:
return res.status_code, res.json()
await asyncio.sleep(int(res.headers.get('retry-after', '5')))
return res.status_code, res.json()
return await asyncio.gather(*[lookup_one(cpf) for cpf in cpf_list])Na Consulta em Tempo Real, use timeout de pelo menos 60 segundos.
Volumes maiores
Para volumes acima de 10.000 consultas por mês, limites por minuto maiores, condições negociadas ou SLA dedicado, fale com a gente sobre o plano Corporativo.
Atualizado em 15 de outubro de 2026