Límites de solicitudes

#El límite

Cada clave puede hacer 120 llamadas por minuto. La API REST y el servidor MCP cuentan en la misma ventana, así que un asistente de IA y una sincronización que comparten clave también comparten su límite; dale una clave a cada uno.

Una sincronización que lee 500 asistentes por página lee 60.000 asistentes dentro del límite, así que una integración bien hecha rara vez lo alcanza. Un bucle que pide lo mismo una y otra vez lo alcanza en un minuto, y para eso está.

#Cómo vas

Cada respuesta, rechazos incluidos, lleva el límite de dos formas: las cabeceras RateLimit del IETF y las cabeceras X-RateLimit-* que leen la mayoría de las bibliotecas cliente.

HTTP/1.1 200 OK
RateLimit-Policy: "default";q=120;w=60
RateLimit: "default";r=117;t=42
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 117
X-RateLimit-Reset: 42

r (remaining) son las llamadas que quedan en esta ventana y t, los segundos que faltan para que empiece una nueva.

#Si te pasas

La llamada se rechaza con 429 Too Many Requests, una cabecera Retry-After en segundos y un problema con "code": "rateLimited". No se ha hecho nada: espera y vuelve a enviarla. Una llamada rechazada cuenta en la actividad de las claves, así que puedes ver cuándo ocurrió.

HTTP/1.1 429 Too Many Requests
Retry-After: 18
Content-Type: application/problem+json

{ "status": 429, "code": "rateLimited", "detail": "This key made more than 120 calls in a minute. Try again in 18 seconds; the RateLimit header says what is left." }

#Cómo mantenerte holgadamente por debajo

• Pide páginas grandes: limit=500 no es problema.
• Sincroniza con updatedSince en lugar de leerlo todo cada vez (Paginación y sincronización).
• Usa webhooks en lugar de consultas periódicas para saber lo que acaba de pasar.
• Envía If-None-Match con el ETag que tienes: un 304 es rápido, aunque sigue contando.
• Haz una pausa cuando la r de RateLimit esté baja, en lugar de esperar a que te rechacen.

La ventana se cuenta por servidor, así que en un día de mucho tráfico una clave puede conseguir de vez en cuando algo más que el límite. No te bases en eso: considera las cabeceras como la referencia.