Rate limits

Para proteger la plataforma y a su iglesia, la API tiene límites de tasa. Si los supera, recibe 429 Too Many Requests.

Cuotas por plan

> Burst = pico instantáneo permitido sobre el promedio.

Límites por endpoint

Algunos endpoints tienen cuota específica más estricta:

Cabeceras de respuesta

Cada response incluye:

X-RateLimit-Limit: 600
X-RateLimit-Remaining: 487
X-RateLimit-Reset: 1714165800     (Unix timestamp en segundos)
X-RateLimit-Bucket: minute

Cuando recibe 429:

HTTP/1.1 429 Too Many Requests
Retry-After: 18

Retry-After indica los segundos a esperar antes del próximo intento.

Estrategia recomendada

import time, requests
 
def call(url):
    for attempt in range(5):
        r = requests.get(url, headers={...})
        if r.status_code != 429:
            return r
        wait = int(r.headers.get('Retry-After', 2 ** attempt))
        time.sleep(wait)
    raise Exception("Rate limit excedido tras 5 intentos")

Cómo el rate limit cuenta

El bucket es por (token, ventana). Significa:

• Token A y token B tienen buckets independientes.
• Pero si comparten el mismo X-Tenant, ambos cuentan contra la cuota del tenant (también).
• Por eso recomendamos un service token por integración, no compartir.

Sugerencias

1. Bulk endpoints: cuando existan, prefiéralos a 1000 calls singulares (POST /v1/members/bulk permite hasta 500 en una llamada).
2. Webhooks vs polling: si su caso es “avísame cuando pase X”, suscríbase al webhook en lugar de hacer polling.
3. ETag para cache: ahorra cuota cuando el dato no cambia (HTTP 304 no cuenta contra el límite de datos, sólo de requests).
4. Pagination amplia: limit=250 mejor que 5 calls de limit=50.
5. Off-hours batch: si tiene un job batch (export nocturno), córralo a las 03:00-05:00 hora del campus principal — son los horarios de menor uso.

Cuotas de webhooks salientes

Ministrium envía webhooks a los endpoints de su iglesia. Si su endpoint responde lento (>3 s) o falla, hay backoff:

• Reintento 1: en 30 s
• Reintento 2: en 5 min
• Reintento 3: en 1 h
• Reintento 4: en 6 h
• Reintento 5: en 24 h
• Tras 5 fallos: webhook se desactiva, email a org_admin.

Mantenga su endpoint rápido (responda 2xx en < 200 ms y procese asíncrono).