Límites de frecuencia y cuotas

Dos tipos de límites mantienen la API rápida para todos:

• El límite de frecuencia de una clave: cuántas solicitudes por segundo puede enviar, con una ráfaga para los picos breves.
• Las cuotas de la organización: cuántas solicitudes pueden enviar todas sus claves juntas por minuto, por día y por mes.

Los dos dependen del plan de la organización. Cada respuesta le indica en qué punto está, así que un cliente bien diseñado nunca tiene que adivinarlo.

Límite de frecuencia de una clave

Cada clave tiene una frecuencia sostenida y una ráfaga. La ráfaga le permite enviar esa cantidad de solicitudes de una vez; después, las solicitudes se admiten a la frecuencia sostenida.

La clase depende del plan de la organización. GET /v1/me muestra la clase, la frecuencia y la ráfaga de la clave que lo llama (rate_limit). El límite se aplica a la clave en su conjunto, independientemente de cuántos servidores de la API atiendan sus solicitudes.

Los endpoints de transmisión, POST /v1/chat (con "stream": true o sin él) y GET /v1/jobs/stream, quedan fuera del límite de frecuencia de la clave: no lo consumen, y sus encabezados RateLimit no tienen el elemento "key". Sí cuentan para las cuotas de la organización, una vez cada uno, cuando empieza la solicitud. Las preguntas tienen sus propios límites, que se describen más abajo.

Cuotas de la organización

Un plan puede fijar cuotas de solicitudes para la organización: por minuto, por día y por mes. Las ventanas son períodos de calendario en UTC: un minuto empieza en el segundo :00; un día, a las 00:00 UTC; un mes, el primer día a las 00:00 UTC. Cuenta cada solicitud con una clave o un token OAuth de la organización, en cualquier dirección. Una solicitud de transmisión cuenta una vez, cuando empieza, dure lo que dure; con la cuota agotada, se rechaza con 429 como cualquier otra solicitud. Una solicitud rechazada con 429 no cuenta.

Los encabezados

Cada respuesta a una solicitud con una clave incluye los límites que se le aplican:

RateLimit-Policy: "key";q=100;w=5, "minute";q=1200;w=60, "day";q=200000;w=86400
RateLimit: "key";r=87;t=1, "minute";r=1150;t=23, "day";r=180311;t=40213
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1

RateLimit-Policy y RateLimit siguen el borrador de IETF RateLimit header fields for HTTP. Cada elemento es un límite:

X-RateLimit-Limit, X-RateLimit-Remaining y X-RateLimit-Reset informan del más estricto de estos límites de forma más sencilla, para los clientes escritos antes de que existiera RateLimit. X-RateLimit-Reset está en segundos.

Cuando se alcanza un límite

La API responde 429 Too Many Requests con un encabezado Retry-After en segundos:

{
  "detail": "the organization has used its API request quota for this period",
  "error": {
    "code": "api.quota_exceeded",
    "message": "the organization has used its API request quota for this period",
    "details": {"quota": "day", "limit": 200000, "reset_at": "2026-10-25T00:00:00Z", "retry_after": 40213},
    "request_id": "01JB7…"
  }
}

Espere lo que indica Retry-After y repita la solicitud. Repita POST y PATCH con la misma Idempotency-Key. Las funciones auxiliares de reintento de Errores hacen ambas cosas.

Otros límites del plan también responden 429 con Retry-After, por ejemplo el número de preguntas por día (limits.questions) o de respuestas en curso al mismo tiempo (limits.concurrent_answers). Trátelos de la misma manera.

Mantenerse dentro de los límites

• Lea RateLimit y reduzca el ritmo cuando r baje, en lugar de esperar a un 429.
• Reparta el trabajo masivo en el tiempo y use los endpoints de lotes donde existan: un lote de 100 documentos es una sola solicitud.
• No consulte los cambios en un bucle continuo. Suscríbase a los webhooks o lea el feed de eventos cada pocos segundos.
• Ejecute los procesos de trabajo en paralelo con un limitador compartido. Varios procesos con una misma clave comparten un mismo límite de frecuencia.
• Pregunte a su contacto en Sursa por una clase superior si su integración necesita más.