Conceptos

Rate limits

Aplican por API key, no por tenant. Si necesitas más, escríbenos a [email protected].

Límites vigentes

  • fwk_test_* — 60 req/min por key.
  • fwk_live_* — 600 req/min por key (10 req/s sostenido).
  • Webhooks entrantes (Culqi / Stripe) — sin límite (filtrados por IP del proveedor).
  • Endpoints públicos no autenticados (/healthz) — rate limit más generoso por IP.

Headers de respuesta

Cada respuesta (incluso las exitosas) incluye los headers RateLimit-* estilo IETF draft-rate-limit-headers. Cuando excedes el límite, devolvemos 429 con Retry-After:

HTTP/1.1 429 Too Many Requests
HTTP/1.1 429 Too Many Requests
RateLimit-Limit: 60
RateLimit-Remaining: 0
RateLimit-Reset: 14
Retry-After: 14
  • RateLimit-Limit — capacidad total del bucket.
  • RateLimit-Remaining — tokens disponibles ahora.
  • RateLimit-Reset — segundos hasta refill completo.
  • Retry-After — segundos a esperar antes del próximo retry seguro (solo presente en 429).

Qué hacer con 429

Espera Retry-After segundos y reintenta con la misma Idempotency-Key. Si tu SDK oficial maneja el retry automáticamente, no necesitas código extra.

No reintentes inmediato

Reintentos sin backoff agravan el problema y te bloquean por más tiempo. Mínimo 100ms entre reintentos incluso si el header permite menos.

Burst y bucket

Usamos token bucket con burst igual a 2× el rate por minuto. Esto significa que puedes hacer 1200 requests en los primeros segundos de tu minuto (en producción), pero a partir de ahí solo recuperas 10 tokens por segundo.

Si tu caso de uso es batch (e.g. emitir 500 facturas de un cierre de mes), distribúyelo con un sleep entre llamadas. Tu SDK oficial trae un helper fw.documents.bulkCreate() que respeta el rate automáticamente.