Docs / API

Los rate limits protegen la plataforma de bursts accidentales y de abuso. Se aplican en tres niveles.

Nivel 1 — Por API key

100 requests por minuto por API key, independiente del endpoint.

Al exceder: respuesta 429 con headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1720440060
Retry-After: 42

Retry-After viene en segundos.

Nivel 2 — Por tenant

1000 requests por minuto por tenant, sumando todas las keys y sesiones. Este límite es raro alcanzar con uso normal — protege de un pipeline mal configurado que quema todas las keys.

Nivel 3 — Por endpoint

Algunos endpoints tienen límites más estrictos por su costo:

Endpoint	Límite adicional
`POST /v1/phishing/upload`	60 requests/minuto por tenant
`POST /v1/phishing/{id}/detonate`	30 requests/hora por tenant
`GET /v1/threats/query`	30 requests/minuto por tenant
`GET /v1/tools/domain-intel`	Consume 1 unit del quota `ip_intel_lookups`

Estos límites reflejan costos de terceros (urlscan.io, VirusTotal, WHOIS providers).

Manejo recomendado

Backoff exponencial

import time
import random

def request_with_backoff(session, url, **kwargs):
    for attempt in range(6):
        r = session.request(url=url, **kwargs)
        if r.status_code != 429:
            return r
        retry_after = int(r.headers.get("Retry-After", "0"))
        wait = max(retry_after, 2 ** attempt + random.random())
        time.sleep(wait)
    raise Exception("rate limited after 6 retries")

Batching

En vez de un request por item, agrupá cuando sea posible:

GET /v1/reports?domain=a,b,c en vez de 3 requests separadas.
GET /v1/threats/iocs?since=<ts> con delta desde el último pull en vez de re-pull completo cada minuto.

Caching

Muchas respuestas son estables — cacheá lo que puedas:

GET /v1/domains — cambia raro. TTL 5 min razonable.
GET /v1/threats/iocs — feed. TTL 5 min razonable (cadence de update del feed).

Concurrencia

Distribuí requests en el tiempo, no en paralelo. Un pipeline con 10 workers pegándole al mismo endpoint agota el rate limit por key en segundos.

Excepciones — Enterprise

En tier Enterprise podés negociar rate limits ampliados si tu use case lo justifica. Común para clientes que integran múltiples SIEMs con pull frecuente.

Debugging

Si empezás a ver 429 en producción:

Chequeá X-RateLimit-* headers para entender si estás cerca del límite normalmente o si hubo un spike.
Mirá /settings/api-keys — ¿alguna key tiene volumen anormal?
Considerá si podés cachear más.
Si es sostenido → contactanos para revisar el límite.