Rate limits

Darwin aplica rate limiting por tenant, distinguiendo entre llamadas read y llamadas write contra la API, y entre eventos de captura on-chain y entregas de webhooks. Esta página describe las cuotas por tier y el comportamiento esperado del cliente cuando se acerca al límite.

Tiers de producto

Los tiers actuales son los siguientes. Los números son representativos y se aplican por tenant, no por usuario.

Tier	Requests / min	Requests / mes	Eventos de captura / mes	Webhook deliveries / mes
Sandbox (evaluación)	60	100.000	5.000	25.000
Starter (producción inicial)	300	1.000.000	50.000	250.000
Growth (escala intermedia)	1.500	10.000.000	500.000	2.500.000
Scale (alto volumen)	7.500	100.000.000	5.000.000	25.000.000
Enterprise	Cuotas a medida	Cuotas a medida	Cuotas a medida	Cuotas a medida

Las llamadas write (eventos prepare, transferencias de custodia, recalls) consumen cuota tanto en requests como en la cuota específica de eventos de captura. Las llamadas read (consultas a NFTs, lineage, reportes) consumen solo la cuota de requests.

Headers de respuesta

Cada respuesta de la API incluye headers con el estado actual de tu cuota:

Header	Significado
X-RateLimit-Limit	Cuota máxima de requests por minuto en tu tier
X-RateLimit-Remaining	Requests restantes en la ventana actual
X-RateLimit-Reset	Timestamp Unix en el que la ventana se reinicia
Retry-After	Cuando se devuelve 429, segundos a esperar antes de reintentar

Comportamiento al exceder el límite

Cuando un request supera el límite por minuto, la API responde con HTTP 429 Too Many Requests y un cuerpo JSON con el detalle del límite excedido:

{
  "error": "rate_limit_exceeded",
  "scope": "requests_per_minute",
  "retryAfter": 12
}

El cliente debe:

1. Leer Retry-After (segundos) o X-RateLimit-Reset (timestamp).
2. Esperar al menos ese tiempo antes de reintentar.
3. Aplicar backoff exponencial con jitter si los 429 persisten, para evitar thundering herd al expirar la ventana.

Las cuotas mensuales (requests, eventos de captura, webhook deliveries) se reinician al primer día UTC del mes calendario. Si una cuota mensual se agota, la API devuelve 429 con scope: "requests_per_month", scope: "events_per_month" o scope: "webhooks_per_month" según corresponda.

Webhooks y rate limiting

Las entregas salientes de webhooks no consumen tu cuota de requests inbound. Tienen su propia cuota mensual por tier (columna Webhook deliveries / mes arriba). Si tu endpoint receptor responde con 429, Tracium respeta el header Retry-After y reintenta dentro de la política de 3 reintentos con backoff exponencial.

Cómo subir de tier

El paso de Sandbox a Starter, de Starter a Growth, de Growth a Scale, o de cualquier tier a Enterprise se acuerda con el área comercial. Las cuotas Enterprise se escriben en el contrato y pueden incluir:

• Burst rates más altos por minuto.
• Cuotas mensuales sin tope o con tope acordado.
• Prioridad en la cola de webhooks.
• SLA de soporte y de disponibilidad.

Contactá al equipo en tech@darwinevolution.io con tu tier actual, tu uso proyectado y el horizonte temporal. Te respondemos con la cuota recomendada y los siguientes pasos.

Buenas prácticas

• Batch por idempotencia: Captia usa UUIDs idempotentes generados por el cliente. Reintentar un evento perdido no genera duplicados ni consume cuota adicional si el servidor ya lo procesó.
• Caché en lectura: las consultas de inventario NFT, ancestry y reportes operacionales soportan caching agresivo del lado del cliente. La metadata canónica no cambia tras el anclaje on-chain.
• GraphQL para queries compuestas: una sola query GraphQL bien formada consume un request en lugar de varios REST. Útil para dashboards.
• Respeta Retry-After: nunca reintentes antes del valor indicado. Reintentos prematuros se cuentan contra tu cuota y prolongan la ventana de bloqueo.