Error 429 en Codex: diagnostica el límite antes de reintentar

Qué significa realmente el mensaje

exceeded retry limit, last status: 429 Too Many Requests confirma dos cosas: el último estado HTTP registrado fue 429 y el cliente dejó de intentarlo al alcanzar su límite de reintentos. No identifica por sí solo la causa.

El origen depende de la ruta que atendió la solicitud. En una sesión vinculada a ChatGPT puede intervenir el uso disponible de Codex; en la API de OpenAI, un 429 puede representar categorías distintas de error; y un gateway o proveedor configurado puede aplicar sus propios límites. Esperar, cambiar de modelo o aumentar los reintentos puede ser correcto en un caso y completamente inútil en otro.

La primera decisión no es cuánto esperar, sino qué servicio respondió con el 429. Para determinarlo hacen falta tres datos: el modo de autenticación, el proveedor efectivo y el detalle completo del error.

Reúne las señales antes de volver a ejecutar la tarea

No vuelvas a lanzar todavía la tarea. Guarda su contexto y anota lo que puedas observar:

• si Codex está autenticado con una cuenta de ChatGPT o usa una API key;
• el proveedor de modelo y la base URL efectivos, sobre todo si existe un gateway o endpoint compatible;
• el texto completo del error, incluido cualquier error.code, request ID, Retry-After u hora de restablecimiento;
• la versión de Codex y si el fallo ocurre en terminal, extensión, nube u otra superficie;
• si falla una sola sesión, un modelo concreto o cualquier tarea nueva;
• cuántas ejecuciones estaban activas y si el problema apareció tras aumentar la concurrencia;
• los indicadores de uso disponibles en la cuenta y el estado operativo del servicio correspondiente.

Estas señales no son pruebas intercambiables. Que /usage muestre actividad alta no demuestra que una API key haya agotado su cuota; que un panel de API tenga saldo no descarta el límite de un gateway; y que otra sesión funcione tampoco convierte automáticamente el fallo original en un problema de velocidad.

No publiques capturas o logs sin revisarlos. Elimina credenciales, tokens, payloads sensibles, datos de cuenta y partes privadas de las URLs. Un request ID puede resultar útil para soporte, pero conviene compartirlo por el canal adecuado y no dejarlo expuesto innecesariamente.

Si Codex está conectado con tu cuenta de ChatGPT

En este recorrido, el primer dato útil es el estado de uso de Codex, no el saldo de la plataforma API. El TUI actual incluye /usage, que permite consultar actividad diaria, semanal o acumulada de tokens de la cuenta de ChatGPT y, cuando la cuenta ofrece esa opción, gestionar un restablecimiento. La documentación de comandos integrados de Codex describe este comando y su alcance.

Los límites no equivalen a un número estable de mensajes. El consumo puede variar con el modelo, el tamaño y la complejidad de la tarea, el contexto acumulado, el razonamiento, las herramientas, la búsqueda y la caché. Además, los mensajes locales y los chats en la nube pueden compartir una ventana de cinco horas y estar sujetos a límites semanales adicionales, según el plan y el modelo. Los valores y condiciones actuales deben comprobarse en la página oficial de límites de uso de Codex.

Actúa según una condición observable:

• Si la interfaz muestra que el límite está agotado y ofrece una hora de restablecimiento, pausa la tarea hasta que esa condición cambie.
• Si existe una opción de restablecimiento para la cuenta, revisa su alcance y coste antes de aceptarla; no presupongas que siempre está disponible.
• Si el uso no explica el fallo, comprueba si afecta a una sesión o modelo concretos y revisa el estado del servicio antes de atribuirlo al plan.
• Si persiste después de que el uso vuelva a estar disponible, registra la hora, versión, superficie, modelo y request ID para escalarlo.

Repetir la misma solicitud mientras el límite de la cuenta sigue activo solo consume tiempo y puede ocultar cuál fue el primer error útil.

Si Codex usa una API key de OpenAI

Cuando la solicitud va realmente a la API de OpenAI, el cuerpo del error y su error.code importan más que la frase genérica “Too Many Requests”. La referencia oficial de errores de la API distingue varias situaciones que pueden devolver 429, como velocidad excedida, saldo o cuota agotados y límites de gasto o uso asociados a una organización o proyecto.

Comprueba que estás mirando la organización y el proyecto que utiliza la clave efectiva. Los límites de velocidad se definen por organización o proyecto, varían según el modelo y se consultan en la vista de límites de la Developer Console, tal como explica la guía oficial de rate limits. Un panel de otro proyecto puede parecer normal y no decir nada sobre la solicitud que falló.

La acción depende de la señal:

• Retry-After o indicación explícita de límite temporal. La respuesta proporciona una condición mínima para reintentar. Espera ese intervalo y reduce la concurrencia o el ritmo.
• Código relacionado con cuota o saldo. Los reintentos no crean cuota disponible. Revisa la facturación, los créditos y el proyecto efectivos.
• Límite de gasto del proyecto u organización. Existe una restricción administrativa. Confirma el límite y quién puede modificarlo.
• Solo aparece 429 sin un código suficiente. La causa aún no está demostrada. Guarda el request ID, el ámbito, el modelo, la hora y las cabeceras que sea seguro compartir.

Para un límite temporal de velocidad, respeta Retry-After cuando exista. En un cliente HTTP propio, si no llega esa cabecera, puede usarse backoff exponencial con jitter, limitando tanto el número de intentos como el tiempo total. La guía de reintentos de la API explica este patrón. No lo conviertas en una espera infinita: no arregla falta de saldo, límites de gasto, permisos ni una configuración equivocada.

También conviene reducir la concurrencia antes de volver a probar. Una única ejecución controlada ayuda a comprobar si el fallo dependía de una ráfaga; lanzar varias sesiones a la vez dificulta esa verificación y puede mantener el límite activo.

Si hay un gateway o proveedor externo

Una API compatible no implica límites idénticos a los de OpenAI. Si model_provider, la base URL o la configuración de red dirigen la solicitud a otro servicio, son su panel, sus cabeceras y sus políticas los que describen el 429 efectivo.

Verifica la ruta completa sin exponer secretos:

1. identifica el proveedor seleccionado por la configuración activa;
2. confirma la base URL final, incluidos proxies y gateways;
3. compara el request ID y la hora con los logs del proveedor;
4. revisa los límites del modelo, cuenta o workspace que atendió la petición;
5. prueba una sola solicitud de alcance reducido únicamente cuando el proveedor indique que puede volver a aceptar tráfico.

Codex permite configurar model_providers.<id>.stream_max_retries para reintentos ante interrupciones SSE; el valor predeterminado documentado es 5 en la referencia de config.toml. Ese ajuste describe cuántos reintentos puede hacer el cliente en ese contexto, no cuánta capacidad concede el proveedor. Aumentarlo sin entender el 429 puede alargar el fallo, generar más solicitudes y retrasar el diagnóstico.

Si el proveedor devuelve una hora de restablecimiento o un límite claro, úsalo como criterio. Si no ofrece información suficiente, escala con la base URL anonimizada, modelo, hora, request ID y una descripción breve de la concurrencia. No atribuyas el caso a OpenAI solo porque Codex sea el cliente visible.

Descarta una incidencia temporal sin asumirla

Una degradación del servicio puede producir respuestas transitorias, pero un 429 aislado no demuestra una incidencia general. Comprueba el estado del servicio que realmente atendió la solicitud y compara la hora exacta del fallo. Después, prueba el alcance de forma controlada:

• una sesión nueva, sin repetir en paralelo la tarea original;
• el mismo recorrido con una operación pequeña y reversible;
• otro modelo, solo si está disponible en el mismo ámbito y el cambio no altera el objetivo;
• la misma cuenta desde la superficie pertinente, si esa comparación es válida para el modo de autenticación.

Interpreta el resultado con cautela. Que una operación pequeña funcione puede indicar capacidad recuperada o un coste menor, pero no prueba que la tarea original vaya a completarse. Que otro modelo funcione puede aislar el alcance, pero no confirma si el origen era capacidad, cuota o una política específica.

Cuándo reanudar, detener o escalar

Reanuda cuando haya cambiado una condición verificable: llegó la hora de restablecimiento mostrada, el panel confirma capacidad disponible, se redujo una ráfaga temporal, el proveedor dio por resuelta una incidencia o se corrigió el proyecto, la base URL o la facturación efectivos. Empieza con una sola ejecución y conserva el primer error completo si vuelve a fallar.

Detén los reintentos si la evidencia apunta a saldo agotado, un límite administrativo, un límite de uso aún activo o una configuración que no controlas. También detente si cada intento devuelve el mismo 429 sin nueva información: subir stream_max_retries no sustituye la intervención necesaria.

Escala cuando la condición que explicaba el error ya se haya resuelto y el fallo persista, o cuando no puedas identificar qué servicio emitió la respuesta. Prepara un informe breve con:

• fecha, hora y zona horaria;
• versión y superficie de Codex;
• modo de autenticación;
• proveedor, modelo y base URL anonimizada;
• error.code, request ID y mensaje completo sin secretos;
• alcance del fallo entre sesiones y modelos;
• concurrencia aproximada y última condición de recuperación comprobada.

Ese conjunto permite investigar sin presentar una hipótesis como un hecho. La recuperación fiable no consiste en encontrar un número mágico de minutos: consiste en relacionar el 429 con el ámbito que lo emitió y volver a ejecutar solo cuando exista una razón comprobable para esperar un resultado distinto.