Límites de peticiones
Cada petición se cuenta dentro de una ventana fija de 60 segundos. El contador que se aplica depende de cómo te autenticas: las claves de API disponen del mayor presupuesto, las sesiones iniciadas de uno holgado y el tráfico anónimo de uno pequeño. Agotado el presupuesto, la API responde 429 y te indica cuánto esperar.
Los tres buckets
El limitador elige exactamente un bucket por petición. Los límites siguientes son los valores por defecto; el operador puede ajustarlos, así que lee las cabeceras de respuesta en lugar de fijar cifras en tu código.
apiKey | por clave de API | 1000 peticiones / min |
authenticated | por usuario (sesión) | 600 peticiones / min |
anonymous | por IP del cliente | 30 peticiones / min |
Las rutas de salud y documentación (/health, /meta/version, /docs y /openapi) nunca se limitan.
Cabeceras de respuesta
Toda ruta con límite declara su política en la respuesta:
X-RateLimit-Limit | Peticiones permitidas en la ventana actual para tu bucket. |
X-RateLimit-Window-Seconds | Duración de la ventana en segundos (60). |
X-RateLimit-Bucket | El bucket aplicado: anonymous, authenticated o apiKey. |
Retry-After | Solo en un 429: segundos que debes esperar antes de reintentar. |
Las respuestas correctas incluyen además variantes por bucket con su nombre como sufijo, p. ej. X-RateLimit-Remaining-apiKey (peticiones restantes en la ventana) y X-RateLimit-Reset-apiKey (segundos hasta que la ventana se reinicia).
La respuesta 429
Una petición limitada devuelve el envoltorio de error estándar con el código estable RATE_LIMITED. Actúa según el código y muestra el mensaje.
{ "error": { "code": "RATE_LIMITED", "message": "ThrottlerException: Too Many Requests", "traceId": "01JGME0Z4E8B3T3Y5F0V9K2QRD" }}Reintentos con espera exponencial
Respeta Retry-After cuando esté presente y recurre a una espera exponencial en su ausencia. Acompaña los reintentos de peticiones que modifican estado con una Idempotency-Key para que una repetición nunca cree un duplicado.
async function callWithRetry(request, maxRetries = 3) { for (let attempt = 0; ; attempt++) { const res = await request(); if (res.status !== 429 || attempt === maxRetries) return res; const seconds = Number(res.headers.get('Retry-After') ?? 2 ** attempt); await new Promise((resolve) => setTimeout(resolve, seconds * 1000)); }}Superficies más estrictas
- Los endpoints de IA (chat, recibos, voz, exportaciones) apilan un segundo limitador indexado por usuario y hogar: un nivel de ráfaga de 10 peticiones por minuto más uno sostenido de 200 por hora por defecto.
- Los endpoints de autenticación bajo /auth/* ejecutan su propio limitador contra la fuerza bruta: 10 intentos por IP y minuto y 5 por cuenta, con bloqueo exponencial de hasta una hora, y responden 429 con el código TOO_MANY_REQUESTS.
- Todos los límites los ajusta el operador. Trata las cabeceras de respuesta, y no las cifras de esta página, como la fuente de verdad.