Rate limits, cuotas y créditos

Para mantener la API estable para todos los clientes aplicamos tres tipos de límite: rate limits (por minuto), cuotas (por mes) y créditos (por operación cara). Cada uno protege un recurso distinto.

1. Rate limit (requests por minuto)

Es el límite de frecuencia de peticiones. Aplica al workspace completo (suma de todas las API keys).

| Plan | Req/min | Burst (segundo) | |------|---------|-----------------| | Starter | 30 | 6 | | Pro | 300 | 30 | | Business | 1.500 | 100 | | Enterprise | custom | custom |

Algoritmo: token bucket con refill linear. El burst evita rechazar ráfagas legítimas siempre que la media se mantenga.

Cabeceras en cada respuesta:

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 287
X-RateLimit-Reset: 1747824060
X-RateLimit-Bucket: workspace_minute

Si excedes, devolvemos 429 Too Many Requests:

{
  "error_code": "rate_limit_exceeded",
  "message": "Has superado el límite de 300 req/min. Reintenta en 12s.",
  "retry_after_seconds": 12
}

Respeta Retry-After. No reintentes inmediatamente.

2. Cuota mensual (requests por mes)

Tope agregado por workspace en el periodo de facturación:

| Plan | Cuota mensual API | |------|-------------------| | Starter | 10.000 | | Pro | 250.000 | | Business | 2.000.000 | | Enterprise | custom |

Cuando llegas al 80% te avisamos por email y Slack. Al 100% las requests devuelven 402 Payment Required con opción de comprar pack adicional desde el dashboard.

Las cuotas se renuevan el día de tu billing anchor (no el día 1 del mes natural).

3. Créditos de enriquecimiento

Los créditos son la moneda para operaciones que requieren cómputo o data externa cara:

| Operación | Créditos | |-----------|----------| | Lectura de empresa por CIF | 0 (gratis) | | Búsqueda en catálogo | 0 (gratis) | | Enriquecimiento firmográfico | 0 (gratis) | | Email genérico de empresa | 1 | | Decisor con cargo | 3 | | Score salud financiera | 5 | | Reverse-geocoding masivo | 0,1 | | Webhook delivery | 0 (gratis) |

Cada plan incluye créditos:

| Plan | Créditos/mes | |------|--------------| | Starter | 500 | | Pro | 5.000 | | Business | 50.000 | | Enterprise | custom |

Si te quedas sin créditos a mitad de mes, puedes comprar packs adicionales (a precio degresivo por volumen) o esperar al renew. Las operaciones que consumen créditos devuelven 402 Insufficient Credits cuando no tienes saldo.

4. Headers de créditos

Cada respuesta incluye:

X-Credits-Used: 3
X-Credits-Remaining: 4892
X-Credits-Plan: 5000
X-Credits-Reset: 2026-06-01T00:00:00Z

5. Cómo evitar 429

Estrategias recomendadas:

• Paginación: usa el cursor next_page_token en lugar de ?offset= para listados grandes.
• Cache local: las empresas cambian poco, cachea localmente 24-72h.
• Bulk endpoints: POST /v1/empresas/batch acepta hasta 100 CIFs por request (cuenta como 1 request).
• Backoff exponencial en cliente: si recibes 429, espera 2^n segundos con jitter.

Ejemplo Python:

import time
import random
import httpx

def request_with_backoff(client, url, headers, max_retries=5):
    for attempt in range(max_retries):
        r = client.get(url, headers=headers)
        if r.status_code != 429:
            return r
        wait = (2 ** attempt) + random.uniform(0, 1)
        time.sleep(min(wait, 60))
    r.raise_for_status()

6. Concurrencia

Independientemente del rate limit por minuto, mantenemos un tope de conexiones simultáneas por workspace: 10 (Starter), 50 (Pro), 200 (Business). Por encima devolvemos 503 Service Unavailable.

Si tu workload requiere más, consulta plan Enterprise.

7. SLA y disponibilidad

• Starter/Pro: best effort, sin SLA contractual.
• Business: 99,5% mensual.
• Enterprise: 99,9% mensual con créditos de penalización.

Estado público en status.leadsbase.es.

Si tu carga es estacional (campañas trimestrales con pico de uso), contacta con hello@leadsbase.es: podemos elevar el rate limit temporalmente sin necesidad de cambiar de plan.

Para entender qué hacer con cada código de error, ver errores comunes.