Un 429 de OpenAI API suele costar tiempo no porque el desarrollador ignore qué es un rate limit, sino porque el mismo código 429 esconde dueños distintos del problema. A veces el owner es la frecuencia de solicitudes. A veces es el volumen de tokens. A veces el freno real está en la cuota, la facturación o el presupuesto. Otras veces el error aparenta ser de capacidad, pero en realidad el request va al project, organization, model o endpoint equivocado. Y en incidentes reales tampoco es raro descubrir que el lector estaba mirando un límite de ChatGPT, Codex o un wrapper, no de Platform API.
Por eso la pregunta útil no es "¿cuál es el rate limit de OpenAI API?", sino "¿qué límite disparó este 429?". Mientras no sepas quién es el owner, comprar créditos, rotar keys o endurecer el retry loop sigue siendo una apuesta.
Muchas guías en español mezclan retroceso exponencial, falta de créditos, cuota insuficiente y consejos de producto como si todos fueran el mismo tipo de 429. La forma útil de ordenar ese ruido no es repetir más recetas, sino leer los headers, contrastar con la página Limits y elegir la acción más pequeña que realmente corresponde.
Respuesta corta
| Pregunta | Respuesta breve |
|---|---|
| ¿Qué suele significar un 429 en OpenAI API? | Que el route actual chocó con un límite de solicitudes, tokens, cuota, facturación, scope o ventana de reset. |
| ¿Qué se revisa primero? | Los x-ratelimit headers y la página Limits de la cuenta. |
| ¿Cuáles son los owners técnicos más frecuentes? | Burst traffic, demasiada concurrencia y requests con demasiado presupuesto de tokens. |
| ¿Cuáles son los owners no técnicos más frecuentes? | Cuota insuficiente, billing issue, final de trial o superficie equivocada. |
| ¿Qué hacer antes de pedir más capacidad? | Bajar concurrencia, poner exponential backoff con jitter, recortar output, sacar trabajo no urgente a colas o Batch API. |
| ¿Qué no hacer a ciegas? | Rotar claves, spamear retries, asumir que créditos equivalen a throughput o confundir ChatGPT/Codex con Platform API. |
Empieza por el owner, no por el retry loop
Si lees con cuidado la guía oficial de rate limits de OpenAI, el contrato es bastante claro. Tu cuenta tiene límites vivos en la página Limits. El usage tier influye en el headroom disponible. Los headers pueden decir cuánto presupuesto queda y cuándo se reabre la ventana. Y las mitigaciones razonables empiezan con backoff y traffic shaping, no con reintentar más rápido.
Eso cambia el orden mental. Un request-rate problem y un token-rate problem pueden verse igual desde fuera porque ambos devuelven 429, pero el arreglo no es el mismo. Un problema de cuota o billing puede parecer un rate problem, pero no se resuelve esperando unos segundos. Un route de project, organization o model mal elegido puede parecer saturación cuando en realidad el fallo es de scope.
La regla operativa que mejor funciona es esta:
- Lee el owner.
- Lee la señal de reset.
- Aplica la corrección mínima segura.
- Escala solo cuando el route, el billing y la forma del tráfico ya están comprobados.
Si tu duda real es de organization, project o key scope, la guía correcta es OpenAI API Key y Organization ID. Si el problema pertenece a límites de producto en Codex o ChatGPT, los siblings correctos son OpenAI Codex usage limits y Codex API key vs subscription.
Qué miden de verdad los límites de OpenAI
OpenAI no describe los rate limits como un único número fijo para todo el mundo. En operación importan varias capas:
- Requests per minute: demasiadas llamadas en una ventana corta.
- Tokens per minute: demasiado volumen de prompt más output, aunque el número de requests parezca moderado.
- Usage tier: la capa de la cuenta afecta al headroom disponible.
- Live account limits: el techo que manda vive en la página Limits, no en una tabla copiada.
- Reset signals: los headers indican cuándo se reabre la ventana.
Esta estructura hace inseguras las tablas viejas del tipo "OpenAI permite X requests por minuto". Son útiles como anécdota histórica, pero peligrosas como regla operativa. Los docs públicos sirven para entender definiciones y patrones; la página Limits es la frontera real de tu cuenta.
También es clave separar request pressure y token pressure. Los problemas RPM llegan por burst, tight loops o concurrencia agresiva. Los problemas TPM aparecen con historiales largos, system prompts demasiado grandes, outputs sobredimensionados o colas de requests que piden más tokens de los que el caso realmente necesita. Si no haces esa separación, acabas aplicando el remedio barato al owner equivocado.
Y un matiz más: aunque tu promedio por minuto parezca correcto, un burst corto dentro de una ventana cuantizada puede fallar antes. Estar "por debajo del promedio" no garantiza que la forma instantánea del tráfico sea segura.
Lee el response antes de cambiar nada
El Cookbook y la guía de rate limits empujan a la misma disciplina: primero lee el response. Los retries fallidos siguen gastando presupuesto. Repetir sin mirar convierte un evento de límite en una espiral más larga.
Los headers más útiles son:
- x-ratelimit-limit-requests
- x-ratelimit-remaining-requests
- x-ratelimit-reset-requests
- x-ratelimit-limit-tokens
- x-ratelimit-remaining-tokens
- x-ratelimit-reset-tokens
Cuando aparecen, esos headers te dan una clasificación inicial muy práctica:
| Señal | Qué suele indicar | Primera acción |
|---|---|---|
| remaining-requests casi en cero | La frecuencia o la concurrencia son demasiado altas | Baja parallelism, suaviza el burst y añade backoff |
| remaining-tokens casi en cero | Prompt y output son demasiado grandes | Recorta prompt, output o mueve trabajo |
| Reset corto | El route probablemente es correcto; el problema es la ventana | Espera al reset y añade jitter |
| Poco headroom en Limits | El cuello está en la cuenta o en el route | Optimiza primero y luego decide si pedir más |
| Headers normales pero sigue fallando | Puede haber scope, billing, wrapper o endpoint incorrecto | Revisa project, org, model y surface |
En un incidente real conviene guardar status, error body, endpoint, model, contexto de project u organization y cualquier valor x-ratelimit. Eso convierte el diagnóstico en evidence, no en memoria.
Una clasificación mínima podría verse así:
tsconst resetRequests = res.headers.get("x-ratelimit-reset-requests"); const resetTokens = res.headers.get("x-ratelimit-reset-tokens"); const remainingRequests = res.headers.get("x-ratelimit-remaining-requests"); const remainingTokens = res.headers.get("x-ratelimit-remaining-tokens"); const owner = remainingRequests === "0" ? "requests" : remainingTokens === "0" ? "tokens" : "unknown"; // Si importan las dos ventanas, usa el reset más tardío.
No necesitas el código perfecto al primer intento. Necesitas no escoger la rama equivocada.
Separa el 429 por owner
1. Request-rate owner
Es el caso clásico de burst. Hay demasiadas llamadas, demasiada concurrencia o un retry loop demasiado agresivo para el route actual. Suele verse con remaining-requests bajo, reset corto y tráfico simultáneo. La solución principal es traffic shaping, no billing.
2. Token-rate owner
Aquí el número de requests puede no parecer alto, pero cada una cuesta demasiado. Historial largo, system prompt sobredimensionado, output cap irreal o contexto excesivo agotan TPM antes de lo esperado. La corrección más barata suele ser recortar tokens, no comprar nada.
3. Quota o billing owner
En esta rama, backoff deja de ser útil como arreglo principal. Si no hay cuota utilizable, el billing está roto o el budget está en el límite, ya no estás ante un problema por minuto. Toca verificar el estado de la cuenta, la tarjeta o el presupuesto. Si tu duda es realmente de créditos y trial, el sibling correcto es OpenAI API free trial.
4. Project, organization o model scope owner
El request puede ser sintácticamente correcto y aun así ir por el route equivocado. Projects distintos pueden tener perfiles diferentes. Un model o un organization distinto pueden cambiar disponibilidad y comportamiento. Copiar settings entre entornos no garantiza que el scope siga siendo el mismo.
5. Wrong product surface owner
Aquí se pierde mucho tiempo. Se mezclan límites de OpenAI Platform API con ventanas de ChatGPT, Codex o gateways compatibles. Un upgrade de ChatGPT no arregla por sí mismo un 429 de la API. Una ventana de uso de Codex no es lo mismo que throughput API. Un wrapper puede imponer su propio rate limit aunque la capa subyacente sea OpenAI-compatible.
Arregla el tráfico con acciones pequeñas y seguras
Una vez que conoces el owner, empieza por la mitigación mínima. Lo que OpenAI repite en sus guías es backoff con jitter, no resend inmediato.
La escalera habitual es esta:
- Espera al reset si el route es correcto.
- Baja concurrencia si el problema es burst.
- Añade exponential backoff con jitter.
- Recorta prompt y output si la presión está en tokens.
- Saca el trabajo no urgente a colas o Batch API.
- Pide más capacidad solo después de estabilizar route y traffic shape.
El error clásico en código es tratar el backoff como decoración. El retry path debería volverse más silencioso después de cada fallo. Un patrón mínimo:
tsconst base = 500; // ms const max = 15000; for (let attempt = 0; attempt < 6; attempt += 1) { const wait = Math.min(max, base * 2 ** attempt); const jitter = Math.random() * 0.25 * wait; await sleep(wait + jitter); }
En presión TPM, recortar tokens suele ser la corrección más barata. Baja el output esperado, acorta historial, elimina contexto inútil. Si el workload no necesita respuesta inmediata, considera Batch API o colas antes de seguir castigando el path síncrono.
Pide más throughput solo con evidencia estable
Muchas veces se intenta escalar demasiado pronto. Eso tapa si la aplicación habría quedado estable con mejor disciplina de tráfico.
Tiene sentido pedir más límites cuando se cumplen todas estas condiciones:
- el route es correcto;
- el billing está sano;
- el owner está identificado;
- los retries ya están acotados;
- el presupuesto de prompt y output es razonable;
- el workload sigue necesitando más capacidad sostenida.
En ese punto sí importan usage tiers e increase requests. Los docs públicos explican la mecánica general, pero el contrato real de subida vive en tu página Limits.
Antes de pedir más capacidad, conviene reunir:
- model y endpoint concretos;
- presión observada de requests y tokens;
- comportamiento de reset;
- perfil de concurrencia;
- optimizaciones ya aplicadas;
- y por qué Batch API o cola no bastan.
Ese paquete sirve tanto para una solicitud formal como para evitar que tu propio equipo pida más límites cuando el problema sigue siendo de arquitectura.
Stop rules
Algunos movimientos son tan frecuentes y tan contraproducentes que merecen su propio checklist.
No hagas esto por defecto:
- Rotar keys. Si el mismo account, project o route sigue siendo el owner, no arregla el problema.
- Comprar créditos sin revisar throughput. Pueden servir para cuota o billing, pero no elevan RPM o TPM automáticamente.
- Subir un plan de ChatGPT o Codex para arreglar un 429 de Platform API.
- Copiar números exactos de tutoriales viejos como si fueran el límite vivo.
- Reintentar a ciegas. Los retries fallidos también consumen budget.
Piensa mejor con esta tabla:
| Si el problema es | Haz lo siguiente |
|---|---|
| Request burst | Baja parallelism y añade jitter |
| Token pressure | Reduce prompt y output size |
| Reset corto | Espera y reintenta de forma segura |
| Billing o quota | Repara el estado de la cuenta |
| Project o model scope | Corrige route y scope |
| Superficie no API | Cambia a la guía de esa superficie |
FAQ
¿Qué significa un 429 en OpenAI API?
Que el route actual superó un límite de requests, tokens, cuota, facturación, scope o reset-window. Primero hay que clasificar quién manda.
¿Dónde viven los límites actuales exactos?
En la página Limits de tu cuenta. Los docs públicos sirven para definiciones y headers; el techo vivo pertenece a la cuenta.
¿Añadir créditos garantiza más throughput?
No. Solo ayuda cuando el owner es cuota o billing. No sube automáticamente request-rate ni token-rate ceilings.
¿ChatGPT Plus, Pro o Codex arreglan un 429 de Platform API?
No. Son superficies distintas con contratos distintos.
¿Cuándo ayuda Batch API?
Cuando el trabajo no es inmediato. Si no necesitas respuesta síncrona, suele ser mejor sacar presión del path en tiempo real.
¿Cuándo conviene pedir más límites?
Después de confirmar route, billing, retries acotados y token budget razonable, y solo si aun así falta capacidad sostenida.
Conclusión práctica
La forma más rápida y honesta de resolver los límites de OpenAI API no es "reintentar más" ni "subir algo". Es identificar el owner, leer la señal de reset y aplicar la corrección mínima segura. Si el owner es requests, suaviza el burst. Si es tokens, reduce el payload. Si es billing o cuota, repara la cuenta. Si es scope, vuelve al project, organization, model o endpoint correcto. Y si el trabajo no es urgente, sácalo del path síncrono cuando Batch API o colas encajan mejor.