Error 429 Claude Code: guía fácil para entenderlo (y el 429 de Codex)

Un error 429 Claude Code significa que chocaste con un límite, y lo primero es saber con cuál. Si usas un plan Pro o Max, casi siempre es tu límite de sesión de cinco horas o tu límite semanal, y Claude Code te muestra «You’ve hit your session limit» con la hora de reinicio. Si usas una clave de API, es el límite de tasa de tu clave o de tu organización, y el mensaje es «Request rejected (429)». En Codex pasa lo mismo: un 429 puede venir del límite de tu plan de ChatGPT, de un límite de tasa breve o de un saldo de API agotado. Aquí tienes una guía rápida para las dos herramientas con los mensajes exactos, las cabeceras que conviene leer y qué hacer en cada caso. Todo sale de la documentación oficial o del propio código de las herramientas, y está enlazado.

Qué significa el error 429 Claude Code

HTTP 429 significa «Too Many Requests», demasiadas peticiones. En la API de Claude llega con el tipo de error rate_limit_error, y la página de errores de la API de Claude da tres causas: tu organización llegó a un límite de tasa, alcanzó el tope de gasto mensual de su nivel o llegó a un límite de gasto en el espacio de trabajo de Claude Code.

Claude Code añade otra fuente que es la que más gente ve, que es la suscripción. Si inicias sesión con una cuenta Pro o Max, tienes un límite de sesión de cinco horas y un límite semanal, y el artículo de soporte sobre Pro y Max dice que esos límites se comparten entre Claude y Claude Code. Cuando se acaba uno, el servidor responde con un 429 que lleva las cabeceras de cuota de tu plan, y Claude Code lo convierte en un mensaje legible.

Todos los mensajes del error 429 Claude Code y qué hacer

Estos son los mensajes que aparecen en la referencia de errores de Claude Code, agrupados según lo que hay detrás.

Mensaje	Qué hay detrás	Qué hacer
You’ve hit your session limit · resets 3:45pm	Tu límite de sesión de cinco horas de Pro o Max	Espera a la hora de reinicio o usa créditos de uso
You’ve hit your weekly limit · resets Mon 12:00am	Tu límite semanal	Lo mismo, pero la espera puede ser de días
You’ve hit your Opus limit / Sonnet limit	El límite de una familia de modelos	Cambia a un modelo de otra familia con /model
Request rejected (429)	El límite de tasa de tu clave de API o de tu proyecto de Amazon Bedrock o Google Cloud	Ejecuta /status, revisa tu nivel y lanza menos agentes a la vez
Server is temporarily limiting requests (not your usage limit)	Una limitación breve del lado de Anthropic	Espera un momento y vuelve a intentarlo

Hay detalles de la documentación que se pasan por alto con facilidad. Los límites de sesión y semanal se comparten entre todos los modelos, así que /model no sirve para ellos, mientras que los límites de Opus y Sonnet solo afectan a esa familia. /usage muestra tus límites y cuándo se reinician, y /usage-credits te deja comprar uso adicional en Pro y Max. Si no quieres estar pendiente del reinicio, Claude Code v2.1.234 o posterior puede esperar en la sesión abierta y continuar solo, y el ajuste de la CLI está en /config como «Continue automatically at usage limit».

El caso que más confunde es ver «Request rejected (429)» pagando una suscripción. La documentación da la causa directamente: una ANTHROPIC_API_KEY olvidada en tu entorno puede mandar las peticiones por una clave de nivel bajo en lugar de por tu suscripción. Ejecuta /status, mira qué credencial está activa y borra la variable si no querías usarla.

Si buscas la lista completa de errores de Claude Code, más allá del 429, la tengo en errores de Claude Code y cómo arreglarlos. Cómo se cuentan los límites de sesión y semanal lo explico en la cuota de Claude Pro y Max.

Qué cabeceras leer ante un error 429 Claude Code

Si llamas a la API tú mismo, o usas Claude Code con una clave de API y quieres saber cuánto margen te queda, las cabeceras de la respuesta dicen más que el mensaje de error. La página de límites de tasa de Claude documenta estas:

Cabecera	Qué te dice
retry-after	Cuántos segundos esperar antes de reintentar. No todos los 429 la llevan, y el 429 por tope de gasto nunca la lleva
anthropic-ratelimit-requests-remaining	Peticiones que te quedan antes del límite
anthropic-ratelimit-tokens-remaining	Tokens que te quedan, redondeados al millar, para el límite más restrictivo
anthropic-ratelimit-input-tokens-remaining / -output-tokens-remaining	Tokens de entrada y de salida que te quedan
anthropic-ratelimit-*-reset	Cuándo se recupera del todo ese límite, en formato RFC 3339

Conviene saber dos cosas sobre cómo funcionan estos límites. La API usa un algoritmo de cubeta de tokens, así que la capacidad se rellena de forma continua y no se reinicia a una hora fija. Y los límites se miden en peticiones por minuto, tokens de entrada por minuto y tokens de salida por minuto para cada clase de modelo, de modo que un 429 puede venir de los tokens aunque hayas enviado pocas peticiones. Puedes ver los límites de tu organización en la página de límites de la consola de Claude.

El tope de gasto es el caso en el que esperar no sirve. Cada nivel tiene un tope mensual (500 dólares en Start, 1.000 en Build y 200.000 en Scale), y al llegar a él el uso se pausa hasta las 00:00 UTC del día 1 del mes siguiente, que son la 1:00 en la España peninsular en invierno. La respuesta sigue siendo un 429 rate_limit_error, pero no trae retry-after y el cuerpo lleva el código enforced_spend_limit_reached. Hasta que se recupere el acceso, cualquier reintento falla, también los automáticos del SDK.

Qué reintenta Claude Code por su cuenta

Claude Code reintenta los 429 temporales con espera exponencial antes de enseñarte nada, hasta 10 veces por defecto. Con una suscripción de claude.ai, desde la v2.1.199 también reintenta los 429 que no llevan las cabeceras de cuota de tu plan. No reintenta un límite real del plan, porque no se va a resolver hasta la hora de reinicio, ni el 429 por límite de gasto de una pasarela. Configurar un modelo de respaldo tampoco ayuda, porque la documentación de configuración de modelos dice que los errores de límite de tasa nunca activan el cambio.

Para ejecuciones desatendidas, como en CI, CLAUDE_CODE_RETRY_WATCHDOG=1 hace que Claude Code reintente sin fin los errores de capacidad 429 y 529. Desde la v2.1.239 falla en el acto con los 429 de gasto o de créditos, en lugar de reintentarlos para siempre.

El 429 en Codex: límite de tasa frente a insufficient_quota

Codex muestra un texto distinto según lo que el servidor devuelve junto con el 429. Revisé el manejo de errores del código abierto de Codex CLI, y los separa así:

Lo que envía el servidor	Lo que muestra Codex	Qué hacer
usage_limit_reached	You’ve hit your usage limit, con la hora de reinicio cuando se conoce	Mira /status, espera al reinicio, compra créditos o usa una clave de API
usage_not_included	To use Codex with your ChatGPT plan, upgrade to Plus	Tu plan no incluye Codex
insufficient_quota, credit_balance_exhausted o un código de límite de gasto	Quota exceeded. Check your plan and billing details.	Añade créditos o sube el límite. Reintentar no sirve
Cualquier otro 429	exceeded retry limit, last status: 429 Too Many Requests	Espera y abre menos sesiones en paralelo

La primera fila es tu plan de ChatGPT. La página de precios de Codex dice que Plus y Business tienen un límite de cinco horas, que Pro no tiene límite de cinco horas por ahora y que también puede haber límites semanales. Cuando se acaba, los usuarios de Plus y Pro pueden comprar créditos, y cualquiera puede seguir en local con una clave de API a precio de API.

La tercera fila es facturación. La página de códigos de error de la API de OpenAI tiene códigos distintos para el saldo prepago agotado y para los límites de gasto de la organización o del proyecto, y avisa de que el tipo de error general puede seguir siendo insufficient_quota. También dice que reintentar errores de facturación, gasto o cuota no devuelve el acceso. Así que si Codex dice «Quota exceeded», ve a la facturación en lugar de esperar.

La última fila es el límite de tasa normal. Codex reintenta las peticiones HTTP 4 veces por defecto (request_max_retries en la referencia de configuración) antes de rendirse con ese mensaje. La guía de límites de tasa de OpenAI dice que los 429 temporales pueden traer Retry-After, que hay que tomarlo como espera mínima y añadir un pequeño retraso aleatorio. Las cabeceras x-ratelimit-remaining-requests, x-ratelimit-remaining-tokens y sus x-ratelimit-reset-* te dicen cuánto queda y cuándo se recupera. OpenAI tiene además un 429 con el código slow_down, que significa que tu ritmo de peticiones subió demasiado rápido.

Cuando no es un 429

Hay dos errores que se parecen pero no tienen nada que ver con tus límites. En Claude, un 529 overloaded_error significa que Anthropic no tiene capacidad para ese modelo. No cuenta contra tu cuota, y cambiar de modelo con /model suele resolverlo. Lo explico en Claude Code error 529. En Codex, el equivalente es un 503, que Codex muestra como «Selected model is at capacity», y lo tienes en Selected model is at capacity en Codex.

Cuando el 429 no cuadra con tu uso

A veces las cuentas no salen, y hay reportes abiertos en las dos herramientas. En el issue #96872 de Claude Code, de septiembre de 2026, un usuario registró 195 errores rate_limit_error mientras su uso de sesión y semanal marcaba 27 % y 26 %, con unas seis sesiones abiertas. En Codex, el issue #57072, del 26 de octubre de 2026, describe 429 con el 99 % del límite semanal disponible, y volver a iniciar sesión lo arregló para ese usuario, al menos un tiempo.

Si te pasa, mira primero /status en la herramienta que uses, cierra las sesiones de más y vuelve a iniciar sesión. Si los números siguen sin cuadrar, abre un reporte con el ID de la petición. Claude lo devuelve en la cabecera request-id, y Codex lo muestra al final del mensaje de reintentos agotados cuando lo tiene. Ninguna de las dos empresas ha explicado cómo cuentan las sesiones en paralelo para estas limitaciones, así que yo no daría por hecho que abrir más sesiones sale gratis.

Si todavía dudas entre las dos herramientas, comparé precios y límites en Claude Code o Codex: cuál pagar.

Preguntas frecuentes sobre el error 429 Claude Code

¿Cambiar de modelo arregla el error 429 Claude Code?

Solo con los límites de la familia Opus o Sonnet. Los límites de sesión y semanal se comparten entre todos los modelos, así que /model no te saca de ahí.

¿Cuánto tengo que esperar?

Usa la hora de reinicio del mensaje. Si es un 429 de la API, sigue retry-after si viene. Si es el tope de gasto del nivel, no hay retry-after y dura hasta las 00:00 UTC del día 1 del mes siguiente, salvo que consigas un límite más alto.

¿Por qué me sale un 429 en Max si casi no lo he usado?

Ejecuta /status y mira si tienes una ANTHROPIC_API_KEY en el entorno, porque entonces Claude Code usa esa clave y no tu plan. Si la suscripción está activa y sigue pasando, probablemente sea una limitación breve del servidor o uno de los fallos de arriba.

¿Reintentar arregla el «Quota exceeded» de Codex?

No. OpenAI dice que reintentar errores de facturación, gasto o cuota no devuelve el acceso. Primero añade créditos o sube el límite de gasto.