Límites de Uso

La API de CPFHub.io tiene dos límites:

• Créditos: cada consulta exitosa consume créditos de la franquicia de tu plan.
• Solicitudes por minuto: un tope de llamadas por minuto en cada tipo de consulta, para proteger la estabilidad de la API.

Los costos de abajo son los valores por defecto. Consulta en el dashboard los costos y las reglas de excedente específicos de tu plan. Los límites por defecto son 30/min en la Consulta Simple (cada envío de lote cuenta como 1) y 5/min en la Consulta en Tiempo Real. Los planes personalizados pueden tener límites distintos, así que confírmalo con el soporte de CPFHub.io. Por encima del límite, la API responde 429 con el header Retry-After. El saldo y el plan actual aparecen en GET /quota, que no consume crédito.

Créditos por plan

El plan Pro del sitio es un selector de volumen, y cada volumen corresponde a uno de los planes de arriba. Los nombres en GET /quota son los nombres en portugués que devuelve la API. Los planes personalizados pueden tener reglas propias, así que revisa las condiciones de tu cuenta en el dashboard. Consulta los precios en cpfhub.io/precos.

Cuándo se renuevan los créditos: en los planes de pago, al inicio de cada ciclo de facturación de la suscripción. En el plan Gratis, el día 1 de cada mes (UTC). El saldo es de toda la cuenta y suma todas las claves.

Costo por consulta

Estos son los costos por defecto. Consulta en el dashboard los costos específicos de tu plan.

Créditos agotados

En los planes sin cobro de excedente, como el Gratis, la API responde 403 cuando el saldo no cubre el costo de la consulta:

• En el lote, el saldo debe cubrir todos los CPF válidos de la lista antes del envío. Si no alcanza, no se cobra nada.
• Un saldo de 1 crédito todavía permite una Consulta Simple, pero no una Consulta en Tiempo Real (1,5 créditos).
• Sigue el saldo en GET /quota, que funciona con créditos en cero y no consume crédito.

Límite por minuto

Estos son los límites por defecto. Los planes personalizados pueden tener límites distintos, así que confírmalo con el soporte de CPFHub.io. Cada envío de lote cuenta como una solicitud de la Consulta Simple. Por encima del límite, la API responde 429 con el header Retry-After.

• El límite vale por clave de API y por tipo de consulta.
• Toda solicitud cuenta, incluso las que responden 404.
• El conteo se reinicia al comienzo de cada minuto del reloj.
• GET /cpf/bulk/{jobId} y GET /quota no entran en el límite.

Al pasar el límite, la API responde 429 con el header Retry-After (segundos hasta liberarse) y no consume 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."
  }
}

El texto de message viene en portugués (límite de solicitudes por minuto excedido, intenta de nuevo en 18 segundos). Espera el tiempo de Retry-After y repite la misma solicitud. Para muchos CPF, usa la consulta por lote: un solo envío procesa hasta 10.000 CPF y cuenta como una solicitud.

Límite por lote

POST /cpf/bulk acepta hasta 10.000 CPF por solicitud. Para volúmenes mayores, divídelos en varias llamadas. Detalles en Consulta por Lote.

La Consulta en Tiempo Real no está disponible por lote.

Uso en volumen

Si prefieres llamadas individuales, limita la concurrencia y respeta el 429:

import asyncio, os
import httpx

CONCURRENCIA = 5

async def process_batch(cpf_list: list[str]):
    semaphore = asyncio.Semaphore(CONCURRENCIA)

    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])

En la Consulta en Tiempo Real, el tiempo típico es de cerca de 1 segundo (no es un SLA). Usa un timeout de al menos 60 segundos.

Volúmenes mayores

Para volúmenes de más de 10.000 consultas al mes, límites por minuto mayores, condiciones negociadas o un SLA dedicado, habla con nosotros sobre el plan Enterprise.

Hablar con el equipo →

Actualizado el 4 de octubre de 2026