Rate Limits

A API CPFHub.io aplica limites de taxa para garantir disponibilidade a todos os clientes. Cada plano tem um limite diferente.

Limites por plano

Plano	Consultas/mês	Rate limit
Gratuito	50	1 req a cada 2s
Starter	1.000	1 req/s
Pro	10.000	1 req/s
Business	100.000	1 req/s
Enterprise	Ilimitado	Sob consulta

✦

Testando sua integração

O plano gratuito inclui 50 consultas por mês - use-as para validar sua integração em produção sem custo. CPFs não encontrados (404) e CPFs com formato inválido (400/422) nunca consomem créditos.

Headers de resposta

Toda resposta da API inclui os seguintes headers de rate limit:

Header	Tipo	Descrição
`X-RateLimit-Limit`	`integer`	Limite de requisições do seu plano (1 no Gratuito equivale a 0,5 req/s)
`X-RateLimit-Remaining`	`integer`	Requisições restantes na janela atual
`X-RateLimit-Reset`	`unix timestamp`	Momento em que a janela reseta
`Retry-After`	`integer`	Segundos para aguardar (presente apenas em respostas 429)

Exemplo de headers em uma resposta 200

HTTP

HTTP/1.1 200 OK
X-RateLimit-Limit: 1
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1747083661
Content-Type: application/json

Exemplo em uma resposta 429 (plano Gratuito)

HTTP

HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 1
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1747083661
Retry-After: 2
Content-Type: application/json

JSON

{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Too many requests. Please retry after 2 seconds."
  }
}

Estratégia de retry

Ao receber um 429, aguarde o número de segundos indicado no header Retry-After antes de tentar novamente. Não use backoff exponencial para 429 - o Retry-After já indica o tempo exato.

TypeScript

async function lookupWithRateLimit(cpf: string) {
  const client = new CPFHub({ apiKey: process.env.CPFHUB_API_KEY })

  while (true) {
    try {
      return await client.lookup(cpf)
    } catch (err) {
      if (err instanceof CPFHubError && err.code === 'RATE_LIMIT_EXCEEDED') {
        const retryAfter = err.headers?.['retry-after'] ?? 1
        await new Promise(resolve => setTimeout(resolve, retryAfter * 1000))
        continue
      }
      throw err
    }
  }
}

Monitorando o consumo

Use os headers X-RateLimit-Remaining e X-RateLimit-Reset para implementar um client-side throttle proativo - evite chegar ao 429 em vez de só reagir a ele:

TypeScript

class ThrottledCPFHub {
  private client = new CPFHub({ apiKey: process.env.CPFHUB_API_KEY })
  private remaining = Infinity
  private resetAt = 0

  async lookup(cpf: string) {
    // Se estamos perto do limite, aguarde o reset
    if (this.remaining <= 1 && Date.now() < this.resetAt) {
      await new Promise(resolve => setTimeout(resolve, this.resetAt - Date.now()))
    }

    const result = await this.client.lookupRaw(cpf) // retorna headers + body
    this.remaining = parseInt(result.headers['x-ratelimit-remaining'] ?? 'Infinity')
    this.resetAt   = parseInt(result.headers['x-ratelimit-reset'] ?? '0') * 1000
    return result.data
  }
}

Uso em volume (batch)

Para processar grandes volumes de CPFs, distribua as requisições respeitando o limite do seu plano:

Python

import asyncio
from cpfhub import AsyncCPFHub

client = AsyncCPFHub(api_key=os.environ["CPFHUB_API_KEY"])

RATE_LIMIT = 1  # req/s - Starter, Pro e Business; use 0.5 no Gratuito

async def process_batch(cpf_list: list[str]):
    semaphore = asyncio.Semaphore(RATE_LIMIT)
    delay = 1.0 / RATE_LIMIT  # intervalo mínimo entre requisições

    async def lookup_one(cpf: str):
        async with semaphore:
            result = await client.lookup(cpf)
            await asyncio.sleep(delay)
            return result

    return await asyncio.gather(*[lookup_one(cpf) for cpf in cpf_list])

Aumentar o limite

Para volumes que requerem rate limits acima de 1 req/s, entre em contato para um plano Enterprise com limites personalizados e SLA dedicado.

Falar com vendas →

Atualizado em 12 de maio de 2026