Rate limits

La Kalipto Devs Platform aplica un rate limit por API key con ventana deslizante de 60 segundos vía Redis. El budget es independiente de los rate limits de v1 y v2. Tu key no comparte cupo con otros namespaces.

Default y configuración

• Por defecto: 60 peticiones por minuto por key.
• Configurable: cada platform_api_keys row tiene un campo rate_limit_per_minute editable desde el dashboard. Pedinos un aumento de cupo si necesitás más.

Cuándo se cuenta

• Se cuenta: cada petición que pasa el filtro de autenticación (key válida + key activa).
• NO se cuenta: peticiones con autenticación fallida (401), porque no llegan a la capa de rate limit.
• NO se cuenta: peticiones rechazadas POR el rate limit (429). Tu key no se “auto-castiga”: el cap es real, no acumulativo.

El last_used_at se actualiza después del check de rate limit, así que un 429 NO actualiza last_used_at.

Response 429

HTTP/1.1 429 Too Many Requests
Content-Type: application/json

{"detail":"rate limit exceeded"}

Estrategia de reintentos recomendada

Espera exponencial con jitter:

import asyncio, random

async def send_with_retry(payload, max_attempts=5):
    for attempt in range(max_attempts):
        resp = await client.post("/platform/v1/messages", json=payload)
        if resp.status_code == 429:
            # 1s, 2s, 4s, 8s, 16s — con jitter ±25%
            base = 2 ** attempt
            jitter = base * (random.random() * 0.5 - 0.25)
            await asyncio.sleep(base + jitter)
            continue
        return resp
    raise RuntimeError("max retries exceeded for /messages")

NO uses reintentos sin espera exponencial. Un ciclo cerrado contra 429 te puede dejar sostenidamente capeado.

Distinguir 429 rate-limit vs 429 cuota

Hay dos fuentes de 429 en POST /platform/v1/messages:

Origen	Body	Acción
Rate limit por key	{"detail":"rate limit exceeded"}	Esperá + reintentá (backoff).
Cuota mensual de templates	{"detail":"template quota exceeded for your plan — upgrade to increase your monthly template limit"}	NO reintentes: subí de plan o esperá al reset mensual.

Distinguilos por el contenido del campo detail. Si dice “template quota exceeded”, parate y notificá a tu sistema. Un reintento te va a devolver exactamente lo mismo.

Quality monitoring (informativo)

Meta también te puede capear por tu cuenta si tu quality score cae. La plataforma persiste el quality_rating por canal y lo expone en el dashboard. Si empezás a ver limitación de tasa de Meta antes de pegarte contra el rate limit nuestro, fijate ahí.

Cuotas mensuales del plan

Plan	Inbound/mes	Templates/mes	Canales
Free	200	0	1
Lite	∞	1.000	2
Pro	∞	10.000	5
Business	∞	∞	∞

Los límites duros se aplican antes de cualquier llamada a Meta. No hay cobro por excedente en v1. Si necesitás más, subí de plan desde el dashboard.