límites de uso de Claude y error 429

¿Cuáles son los límites de uso de Claude?

Los límites de uso de Claude se dividen en dos sistemas distintos. Primero debe identificar cuál de ellos ha bloqueado su acceso. Una suscripción de Claude (Pro, Max, Team o Enterprise) ofrece un cupo de uso rotativo compartido entre modelos y con Claude chat; el sistema le detendrá con un mensaje como You've hit your session limit · resets 3:45pm. La API de Claude mide un parámetro distinto: la velocidad de envío de peticiones y tokens, contada por minuto. El sistema le detendrá con un error HTTP 429 de tipo rate_limit_error y un encabezado retry-after que indica cuántos segundos debe esperar.

Las soluciones para ambos casos son totalmente distintas. Un límite de suscripción depende de la cantidad de uso dentro de un intervalo de tiempo; debe esperar al reinicio del ciclo o adquirir más capacidad. Un límite de tasa (rate limit) de la API depende de su velocidad actual y se libera en segundos si reduce la frecuencia de las peticiones.

Los niveles de cuota de los planes y de los límites de tasa cambian con frecuencia. Dado que un valor incorrecto es peor que no tener ninguno, no se muestran valores específicos aquí. Consulte sus propios valores con los comandos que se presentan más adelante.

¿Qué límite ha alcanzado? Lea el mensaje exacto

Claude Code indica el sistema en el texto impreso. Identifique el suyo antes de realizar cambios.

• You've hit your session limit · resets 3:45pm es un límite de suscripción. Se ha agotado el cupo rotativo de su plan para este periodo.
• You've hit your weekly limit · resets Mon 12:00am es el mismo sistema para el periodo de tiempo más largo.
• You've hit your Opus limit · resets 3:45pm es un límite de suscripción que se aplica solo a peticiones Opus. Este es el único caso donde cambiar el modelo ayuda.
• API Error: Request rejected (429) · this may be a temporary capacity issue. If it persists, check https://status.claude.com. es un límite de tasa (rate limit) de la API. Ha alcanzado el límite configurado para su API key, o para su proyecto de Amazon Bedrock o Google Cloud.
• API Error: Server is temporarily limiting requests (not your usage limit) es una restricción temporal no relacionada con la cuota de su plan. Claude Code reintenta la operación automáticamente con backoff antes de mostrar este mensaje.

Límites de suscripción: sesión, semanal y la ventana Opus

Un plan de suscripción incluye un límite de uso rotativo. Cuando se agota, Claude Code bloquea las solicitudes adicionales hasta la hora de reinicio indicada en el mensaje. Dos propiedades de este límite causan la mayoría de las confusiones.

• Se comparte con Claude chat. El trabajo realizado en claude.ai consume el mismo límite que el trabajo en la terminal; un uso intensivo en el chat reducirá el tiempo disponible para programar.
• Se comparte entre modelos. Los límites de sesión y semanales no tienen un presupuesto por modelo, con la única excepción del límite de Opus.

En Claude for Teams y Enterprise, el formato documentado es un límite por usuario que se reinicia en una ventana rotativa de cinco horas y una ventana semanal. Este límite se comparte con Claude chat y Cowork, y su tamaño depende del nivel de la cuenta (Standard o Premium). En Pro y Max, el tiempo de reinicio mostrado en el mensaje y sus propias barras /usage son los valores exactos, no una cifra copiada de un blog. Si aún está eligiendo un plan, qué plan de Claude necesita compara las restricciones de cada uno.

Por qué cambiar de modelo con /model no restaura el acceso

Este es el error más común y la documentación es clara al respecto: los límites de sesión y semanales se comparten entre todos los modelos, por lo que cambiar de modelo no restaura el acceso. Seleccionar un modelo más pequeño después de agotar el intervalo de sesión solo cambia el modelo que respondería. No cambia el saldo restante, ya que el límite no se asigna por modelo; por lo tanto, el cambio no libera capacidad.

La excepción es el límite de Opus, que es un tope específico para ese modelo. Si el mensaje indica You've hit your Opus limit, entonces /model es la solución correcta. Cambie a otro modelo para continuar trabajando, ya que solo las solicitudes de Opus están bloqueadas.

Considerar el límite como un error es el segundo error común. Reinstalar o volver a autenticar no cambia nada. El saldo se restablece cuando el intervalo se reinicia o cuando se compran créditos de uso.

Qué hacer cuando se alcanza el límite de suscripción

1. Revisa la hora de reinicio. El intervalo de una sesión es corto. El intervalo semanal no es algo que debas esperar sentado en tu escritorio.
2. Si es el límite de Opus, ejecuta /model y elige otro modelo.
3. Ejecuta /usage para ver los límites de tu plan, tus barras de progreso y cuándo se reinician. /cost es un alias para la misma pantalla.
4. Ejecuta /usage-credits para seguir trabajando después de alcanzar el límite. En Pro y Max abre la configuración de facturación. En Team y Enterprise abre la configuración de uso de la organización, o envía una solicitud a los administradores si no tienes acceso a facturación.
5. Si alcanzas el mismo límite cada semana, el plan no es adecuado para tu flujo de trabajo.

/usage-credits requiere una suscripción a claude.ai iniciada sesión mediante /login. No está disponible con autenticación por API key, ya que una API key no tiene un límite de plan que extender.

Los créditos de uso tienen un efecto secundario importante. La vida útil del prompt cache es de una hora con suscripción y baja a cinco minutos una vez que se utilizan créditos; por lo tanto, más turnos comienzan sin caché y el Claude Code token usage aumenta para el mismo trabajo.

Mensajes que parecen límites de uso pero no lo son

Claude Code reporta cuatro errores como límites de uso, pero ninguno de ellos lo es.

• Una advertencia de context o auto-compact no es un límite de uso. /context imprime una línea como Context exceeds the 200k-token limit by 94k tokens — run /compact or /clear to continue. cuando la conversación supera la ventana de contexto del modelo. El historial antiguo se resume para liberar espacio y no afecta el límite de su plan.
• Error during compaction: Conversation too long. Press esc twice to go up a few messages and try again. significa que /compact falló porque no hay suficiente contexto libre para contener el resumen que generaría.
• Credit balance is too low significa que su organización en Console se ha quedado sin créditos prepagados. Añada créditos en platform.claude.com/settings/billing, donde también puede activar la recarga automática.
• API Error: Usage credits required for 1M context · run /usage-credits to turn them on, or /model to switch to standard context es una verificación de permisos, no un agotamiento de cuota. Seleccione la variante del modelo sin el sufijo [1m] o configure CLAUDE_CODE_DISABLE_1M_CONTEXT=1.

Otro error proviene de la API. Un 413 request_too_large es un límite de tamaño para una sola petición, no un límite de tasa (rate limit).

Límites de tasa de la API: qué cuenta realmente el error 429

La Messages API mide tres parámetros, de forma independiente para cada clase de modelo.

• solicitudes por minuto (RPM)
• tokens de entrada por minuto (ITPM)
• tokens de salida por minuto (OTPM)

Su organización también tiene un límite de gasto, que es un concepto distinto: un costo mensual máximo para el uso de la API. Una vez alcanzado el tope de gasto de su nivel (tier), el uso de la API se detiene hasta el siguiente mes, a menos que solicite un límite superior. Ningún bucle de reintentos (retry loop) puede solucionar esto.

Cuatro mecanismos determinan cuándo ocurre el error 429.

• Los límites son por clase de modelo. Se aplican por separado a cada modelo, por lo que puede usar diferentes modelos hasta sus respectivos límites de forma simultánea. Algunas familias comparten un contenedor: el límite de tasa de Opus es el total de Claude Opus 4.8, Opus 4.7, Opus 4.6 y Opus 4.5, mientras que Claude Sonnet 5 tiene el suyo propio.
• La capacidad se recarga continuamente. La API utiliza un algoritmo de token bucket, por lo que la capacidad se repone continuamente en lugar de reiniciarse en un momento fijo. Un límite de 60 solicitudes por minuto puede aplicarse como una solicitud por segundo; por tanto, enviar 60 solicitudes a la vez resultará en error.
• En la mayoría de los modelos, solo la entrada sin caché cuenta para el ITPM. input_tokens y cache_creation_input_tokens cuentan. cache_read_input_tokens no cuenta en la mayoría de los modelos Claude, siendo Claude Haiku 3.5 la excepción documentada. Por lo tanto, el uso de caché proporciona margen de maniobra en los límites de tasa y también un descuento. En cuanto a la salida, un max_tokens alto no cuenta contra el OTPM, ya que el OTPM solo cuenta los tokens realmente producidos.
• Los límites residen a nivel de organización. Se puede asignar un límite inferior a un workspace, pero los límites de la organización siempre se aplican incluso si la suma de los límites de los workspaces es mayor. Un límite que no haya sobrescrito en un workspace se hereda de la organización; no queda ilimitado.

Los niveles denominados Start, Build, Scale y Custom definen los valores reales, asignados automáticamente según su historial de uso y estado de la cuenta. Las organizaciones nuevas pueden comenzar por debajo de los límites estándar publicados, por lo que el primer 429 puede aparecer antes de lo que predice una tabla. Un aumento brusco en el uso activa los límites de aceleración, que devuelven un 429 aunque todavía esté dentro de su nivel; aumente el tráfico de forma gradual. Cada cifra publicada es un techo: los límites documentados son el uso máximo permitido, no mínimos garantizados. Para solicitar más, utilice el control "Request rate limit increase" en la página Limits de la Claude Console.

Lectura de un 429: retry-after, los headers y reintentos del SDK

Cada error de la API devuelve el mismo contenedor: un objeto error anidado que contiene el tipo y el mensaje, además de un request_id de nivel superior.

{
  "type": "error",
  "error": {
    "type": "rate_limit_error",
    "message": "<names the rate limit you exceeded>"
  },
  "request_id": "req_011CSHoEeqs5C35K2UUqR7Fy"
}

Los headers contienen el resto de la información.

• retry-after es el número de segundos a esperar antes de reintentar la solicitud. Los reintentos prematuros fallarán.
• anthropic-ratelimit-requests-limit, anthropic-ratelimit-requests-remaining y anthropic-ratelimit-requests-reset describen el presupuesto de su solicitud.
• anthropic-ratelimit-input-tokens-* y anthropic-ratelimit-output-tokens-* hacen lo mismo para ITPM y OTPM, con los mismos sufijos limit, remaining y reset.
• anthropic-ratelimit-tokens-* muestra los valores para el límite más restrictivo aplicado actualmente.

Los headers de reset son marcas de tiempo RFC 3339. Los headers de tokens restantes se redondean al millar más cercano; léalos como una referencia aproximada. El modo fast tiene su propio pool y sus propios headers anthropic-fast-*. Puede leer todos ellos en cualquier llamada exitosa:

curl -s -D - -o /dev/null https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"claude-sonnet-5","max_tokens":16,"messages":[{"role":"user","content":"hi"}]}' \
  | grep -i 'ratelimit\|retry-after\|request-id'

Cada respuesta también incluye un header request-id único, como req_018EeWyXxfu5pfWkrYcMdjWG. Aparece como request_id en los cuerpos de error y como _request_id en las respuestas de los SDK de Python y TypeScript. Inclúyalo al contactar con soporte técnico.

Verifique si realmente necesita un bucle de backoff antes de implementarlo. Los SDK oficiales reintentan automáticamente los fallos transitorios, incluyendo errores de conexión, límites de tasa (rate limits) y errores de servidor 5xx, utilizando backoff exponencial. Por defecto se realizan dos reintentos, respetando el header retry-after cuando está presente. Cada cliente acepta una opción maximum-retries para cambiar o deshabilitar este comportamiento.

import anthropic

client = anthropic.Anthropic(max_retries=5)  # the SDK default is 2

try:
    msg = client.messages.create(
        model="claude-sonnet-5",
        max_tokens=1024,
        messages=[{"role": "user", "content": "hello"}],
    )
except anthropic.RateLimitError as err:
    headers = err.response.headers
    print("still limited after retries; wait", headers.get("retry-after"), "seconds")
    print("request id:", headers.get("request-id"))

529 overloaded_error no es su culpa

Un error 429 indica que ha realizado demasiadas solicitudes en poco tiempo. Un error 529 overloaded_error indica que la API está temporalmente sobrecargada; esto ocurre cuando la API experimenta un tráfico elevado de todos los usuarios. El error no se debe a su clave ni a su código. Reintente la operación usando exponential backoff, acción que los SDKs ya ejecutan para respuestas 5xx, y verifique status.claude.com si el problema persiste. Un error 500 api_error es un error interno que debe reintentar de la misma manera; ninguno de estos errores es un límite de tasa (rate limit).

Consulte sus propios límites en lugar de una tabla

En una suscripción, /usage es la pantalla relevante. Muestra las barras de uso de su plan y el desglose del consumo, y los interruptores d o w permiten alternar entre las últimas 24 horas y los últimos 7 días. Dos advertencias. El bloque Session muestra el uso de tokens de API y está diseñado para usuarios de API; los suscriptores pueden ignorar su cifra en dólares. Los datos provienen del historial de sesión local de esa máquina, por lo que falta el uso proveniente de otros dispositivos o de claude.ai.

En el lado de la API, la página Usage en la Claude Console genera dos gráficos: "Rate Limit - Input Tokens" y "Rate Limit - Output Tokens". El gráfico de entrada muestra el máximo por hora de tokens de entrada sin caché por minuto frente a su límite ITPM actual, con su tasa de caché a un lado; esto permite monitorear la aproximación al límite para evitar alcanzarlo en producción.

Para leer sus límites configurados mediante programación:

curl -s https://api.anthropic.com/v1/organizations/rate_limits \
  -H "x-api-key: $ANTHROPIC_ADMIN_KEY" \
  -H "anthropic-version: 2023-06-01"

Requiere una clave Admin API, y GET /v1/organizations/workspaces/{workspace_id}/rate_limits realiza la misma función por workspace. Ambos son de solo lectura: para cambiar un límite, use la pestaña Limits en la Console.

Usar less para evitar límites

Ambos sistemas miden lo mismo internamente, por lo que estos ajustes funcionan en cualquiera de ellos.

• Gastar menos tokens por turno. Las sesiones continuas mantienen el cache activo, y /clear entre tareas no relacionadas no tiene coste. Uso de tokens de Claude Code explica estos ajustes detalladamente.
• Reducir el esfuerzo. Los niveles son low, medium, high, xhigh y max. El menú /effort también ofrece ultracode, que aumenta el gasto en lugar de reducirlo. El razonamiento profundo no es necesario para un renombrado mecánico.
• Reducir la concurrencia tras un error 429. Baja el valor de CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY y evita usar muchos subagentes en paralelo. Ejecuta también /status: un ANTHROPIC_API_KEY accidental redirige las peticiones a una clave de nivel bajo en lugar de usar tu suscripción.
• Trasladar el trabajo no interactivo a la Message Batches API. Procesa grandes volúmenes de forma asíncrona con un 50% de descuento en tokens de entrada y salida. Tiene sus propios límites de tasa, por lo que un proceso nocturno no competirá con tu sesión.

El trabajo intensivo ejecutado por un programa en lugar de una persona debe usar una API key desde el principio. Tu primera app de Claude API en un VPS cubre la gestión de claves y reintentos; además, una ejecución larga de un agente sobrevive a una desconexión si mantienes Claude Code ejecutándose en un VPS dentro de tmux.

FAQ

¿Por qué cambiar de modelo no soluciona mi límite de uso de Claude?

Porque los límites de sesión y semanales se comparten entre todos los modelos. El cupo pertenece al plan y no a un modelo específico; por lo tanto, /model solo cambia el modelo que responde, no el saldo restante. La única excepción es You've hit your Opus limit, que se aplica únicamente a las solicitudes de Opus. En ese caso, cambiar de modelo es la solución documentada.

¿Qué significa el error 429 rate_limit_error y cuánto debo esperar?

Significa que su cuenta ha alcanzado un límite de tasa para esa clase de modelo: solicitudes por minuto, tokens de entrada por minuto o tokens de salida por minuto. La respuesta incluye un encabezado retry-after con los segundos de espera, y los reintentos prematuros fallarán. Los SDK oficiales ya reintentan los límites de tasa y los errores 5xx con backoff exponencial, dos veces por defecto, respetando dicho encabezado. Un error 429 que ocurre mientras aún está dentro de los límites de su nivel indica un límite de aceleración debido a un aumento repentino de la carga.

¿Cómo puedo ver mis límites de uso de Claude y cuándo se reinician?

En Claude Code, ejecute /usage para ver las barras de su plan, los tiempos de reinicio y un desglose de uso; /cost es un alias, y d o w alterna entre las últimas 24 horas y los últimos 7 días. Esos datos provienen del historial de la sesión local, por lo que no incluyen el uso de otros dispositivos ni de claude.ai. En la API, la Console muestra sus límites de tasa, y GET /v1/organizations/rate_limits devuelve sus límites configurados con una clave de Admin API.

¿Puedo seguir trabajando después de alcanzar mi límite del plan de Claude?

A veces. Ejecute /usage-credits para comprar uso adicional tras alcanzar el límite en los planes Pro y Max, o para solicitarlo a un administrador en los planes Team y Enterprise; requiere un inicio de sesión en claude.ai mediante /login y no está disponible con autenticación por clave API. De lo contrario, espere al tiempo de reinicio, cambie de modelo si se trataba del límite de Opus, o traslade el trabajo a una clave API, la cual mide el uso por minuto en lugar de por ventana de tiempo.