CPFHub.io

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 siteNome em GET /quotaCréditos por períodoAo esgotar
GrátisGrátis50A API para e responde 403 até a renovação
ProMicro100Continua consultando; o excedente é cobrado na fatura seguinte
ProBásico1.000Continua consultando; o excedente é cobrado na fatura seguinte
ProIntermediário5.000Continua consultando; o excedente é cobrado na fatura seguinte
ProAvançado10.000Continua consultando; o excedente é cobrado na fatura seguinte
CorporativoPlano personalizadoSob consultaNegociado

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

ConsultaCusto
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:

OndeMensagemFormato de error
Consulta Simples e Consulta em Tempo RealLimite de créditos excedidoObjeto (error.message)
Envio de lote de CPF, saldo menor que a lista ou zeradoCréditos insuficientes para o lote: N necessários.Objeto (error.message)
Envio de lote de CNPJ, saldo menor que a lista ou zeradoCréditos insuficientes para o lote.Objeto (error.message)
Consulta de CNPJLimite de créditos excedidoEm 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

ConsultaLimite 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} e GET /quota nã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
HTTP/1.1 429 Too Many Requests
Retry-After: 18
JSON
{
  "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:

Python
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.

Falar com a equipe →


Atualizado em 15 de outubro de 2026