Límites de uso de Claude: qué hacer al alcanzarlos

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

Los límites de uso de Claude se dividen en dos sistemas independientes. Lo primero es determinar cuál de los dos le bloqueó. Una suscripción de Claude (Pro, Max, Team o Enterprise) proporciona una cuota de uso renovable que se comparte entre los modelos y con Claude chat. Cuando se agota, aparece un mensaje como You've hit your session limit · resets 3:45pm. La API de Claude mide otra cosa: la velocidad a la que envía solicitudes y tokens, contabilizada por minuto. Cuando se supera, devuelve un error HTTP 429 de tipo rate_limit_error y una cabecera retry-after que indica cuántos segundos debe esperar.

Las soluciones no tienen nada en común. El límite de una suscripción depende de cuánto ha usado dentro de una ventana. Debe esperar al reinicio o comprar más uso. El límite de velocidad de la API depende de la velocidad actual. Desaparece en unos segundos cuando reduce el ritmo.

Las cuotas de los planes y los números de nivel de los límites de velocidad cambian con frecuencia. Un número incorrecto es peor que no indicar ninguno, por lo que no se muestran aquí. Consulte los suyos con los comandos que aparecen más abajo.

¿Qué límite alcanzó? Lea el mensaje exacto

Claude Code indica el sistema en el texto que muestra. Identifique el suyo antes de cambiar nada.

• You've hit your session limit · resets 3:45pm es un límite de suscripción. Ha consumido la asignación variable de su plan para esta ventana.
• You've hit your weekly limit · resets Mon 12:00am es el mismo sistema, pero aplicado a la ventana más larga.
• You've hit your Opus limit · resets 3:45pm es un límite de suscripción que sólo se aplica a las solicitudes de Opus. Este es el único caso en el que cambiar de 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 velocidad de la API. Ha alcanzado el límite configurado para su API key o para su proyecto de Amazon Bedrock o Google Cloud. Cuál se aplica depende de cómo se autentica el cliente, ya que un cliente de Bedrock o Vertex se contabiliza contra la cuota de su proyecto en la nube y no contra la de una organización de Anthropic.
• API Error: Server is temporarily limiting requests (not your usage limit) es una limitación temporal no relacionada con la cuota de su plan. Claude Code vuelve a intentarlo automáticamente con un intervalo creciente antes de mostrarle esa línea.

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

Un plan de suscripción incluye una cuota de uso móvil. Cuando se agota, Claude Code bloquea las solicitudes posteriores hasta la hora de restablecimiento que aparece en el mensaje. Dos propiedades de esta cuota causan la mayoría de las confusiones.

• Se comparte con Claude chat. El trabajo que realiza en claude.ai consume la misma cuota que el trabajo en el terminal, por lo que una tarde con mucho uso del chat reduce el tiempo disponible para programar por la noche. Todas las interfaces en las que inicia sesión con esa cuenta consumen el mismo fondo. Por tanto, en Linux la aplicación de escritorio beta y la CLI de Claude Code consumen una sola cuota entre ambas, no una cada una.
• Se comparte entre modelos. Los límites de sesión y semanales no tienen un presupuesto por modelo, con una única excepción: el límite de Opus.

En Claude for Teams y Enterprise, la estructura documentada consiste en una cuota por puesto que se restablece mediante una ventana móvil de cinco horas y una ventana semanal. Se comparte con Claude chat y Cowork, y su tamaño depende del nivel del puesto (Standard o Premium). En Pro y Max, la hora de restablecimiento que aparece en el mensaje y sus propias barras /usage son los valores fiables, no una cifra copiada de una publicación de blog. Si todavía está eligiendo un nivel, qué plan de Claude necesita compara las funciones que habilita cada uno.

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

Este es el error más habitual, y la documentación es clara: los límites de sesión y semanales se comparten entre todos los modelos, por lo que cambiar de modelo no recupera el acceso. Elegir un modelo más pequeño después de agotar la ventana de sesión cambia el modelo que respondería. No cambia la cantidad de uso disponible, porque el límite nunca se asignó por modelo y, por tanto, el cambio no tiene nada que liberar.

La excepción es el límite de Opus, que sí es específico del modelo. Si el mensaje muestra You've hit your Opus limit, /model es la solución correcta. Cambie a otro modelo y siga trabajando, porque sólo se bloquearon las solicitudes a Opus.

Considerar que el límite es un error es el segundo paso equivocado. Reinstalar o volver a autenticarse no cambia nada. El uso disponible se restablece cuando se reinicia la ventana o cuando compra créditos de uso.

Qué hacer cuando alcanzas un límite de suscripción

1. Consulta la hora de restablecimiento. Una ventana de sesión es corta. Una ventana semanal no se resuelve esperando en el escritorio.
2. Si se trata del límite de Opus, ejecuta /model y selecciona otro modelo.
3. Ejecuta /usage para consultar los límites de tu plan, sus barras y cuándo se restablecen. /cost es un alias de 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 tu organización o envía una solicitud a los administradores si no tienes acceso a la facturación.
5. Si alcanzas el mismo límite todas las semanas, el plan no tiene el tamaño adecuado para tu forma de trabajo. Conviene valorar una vez las opciones para superar un límite de uso, en lugar de hacerlo en cada restablecimiento.

/usage-credits necesita una suscripción de claude.ai iniciada mediante /login. No está disponible con autenticación mediante clave de API, porque una clave de API no tiene una asignación de plan que se pueda ampliar.

Los créditos de uso tienen un efecto secundario que conviene conocer de antemano. La duración de la caché de indicaciones es de una hora con una suscripción y se reduce a cinco minutos cuando utilizas créditos. Por eso, más turnos comienzan sin caché y aumenta el uso de tokens de Claude Code para el mismo trabajo.

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

Cuatro errores de Claude Code se notifican como límites de uso, pero ninguno lo es.

• Una advertencia de contexto o de compactación automática no es un límite de uso. /context muestra 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 la asignación de tu plan no se modifica.
• Error during compaction: Conversation too long. Press esc twice to go up a few messages and try again. significa que /compact ha fallado porque no queda suficiente contexto libre para almacenar el resumen que generaría.
• Credit balance is too low significa que tu organización de Console ha agotado los créditos prepagados. Añade créditos en platform.claude.com/settings/billing, donde también puedes 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 comprobación de autorización, no una cuota agotada. Selecciona la variante del modelo sin el sufijo [1m] o configura CLAUDE_CODE_DISABLE_1M_CONTEXT=1.

Hay otro error que procede de la API. Un error 413 request_too_large indica un límite de tamaño para una única solicitud, no un límite de velocidad.

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

La Messages API mide tres valores, por separado 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 otra cosa: un coste mensual máximo para el uso de la API. Cuando alcanza el límite de gasto de su nivel, el uso de la API se pausa hasta el mes siguiente, salvo que solicite un límite superior. Ningún bucle de reintentos resuelve esa situación.

Cuatro mecanismos determinan cuándo llega el error 429.

• Los límites se aplican por clase de modelo. Se aplican por separado a cada modelo, por lo que puede usar distintos modelos simultáneamente hasta alcanzar sus respectivos límites. Algunas familias comparten un depósito: el límite de velocidad de Opus es un total para Claude Opus 4.8, Opus 4.7, Opus 4.6 y Opus 4.5, mientras que Claude Sonnet 5 tiene el suyo.
• La capacidad se repone de forma continua. La API usa un algoritmo de depósito de tokens, 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, de modo que 60 solicitudes enviadas a la vez siguen fallando.
• En la mayoría de los modelos, sólo las entradas que no están en caché cuentan para ITPM. input_tokens y cache_creation_input_tokens cuentan. cache_read_input_tokens no cuenta en la mayoría de los modelos Claude; Claude Haiku 3.5 es la excepción documentada. Por tanto, la caché proporciona margen adicional para los límites de velocidad, además del descuento. En el caso de la salida, un valor alto de max_tokens no cuenta para OTPM, porque OTPM sólo cuenta los tokens generados realmente.
• Los límites se aplican a nivel de organización. Un espacio de trabajo puede tener asignado un límite inferior, y los límites de toda la organización siempre se aplican aunque la suma de los límites de los espacios de trabajo sea superior. Un límite que no haya sobrescrito en un espacio de trabajo se hereda de la organización; no queda ilimitado.

Los niveles Start, Build, Scale y Custom establecen los valores reales. Se asignan automáticamente según el historial de uso y el estado de la cuenta. Las organizaciones nuevas pueden empezar por debajo de los límites estándar publicados, por lo que el primer error 429 puede llegar antes de lo que indica una tabla. Un aumento brusco del uso activa límites de aceleración, que devuelven el error 429 aunque todavía se encuentre dentro de los límites de su nivel. Por tanto, aumente el tráfico gradualmente. Todas las cifras publicadas son límites máximos: los límites documentados representan el uso máximo permitido, no mínimos garantizados. Para solicitar un aumento, use el control "Request rate limit increase" en la página Limits de Claude Console.

Leer un 429: retry-after, las cabeceras y los reintentos del SDK

Todos los errores de API devuelven el mismo contenedor: un objeto error anidado que incluye el tipo y el mensaje, además de un campo request_id de nivel superior.

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

El resto se encuentra en las cabeceras.

• retry-after indica el número de segundos que debe esperar antes de volver a intentar la petición. Los reintentos anteriores fallarán.
• anthropic-ratelimit-requests-limit, anthropic-ratelimit-requests-remaining y anthropic-ratelimit-requests-reset describen el presupuesto de la petición.
• anthropic-ratelimit-input-tokens-* y anthropic-ratelimit-output-tokens-* hacen lo mismo para ITPM y OTPM, con los mismos sufijos de límite, disponible y restablecimiento.
• anthropic-ratelimit-tokens-* muestra los valores del límite más restrictivo que está activo en ese momento.

Las cabeceras de restablecimiento contienen marcas de tiempo RFC 3339. Las cabeceras de tokens restantes se redondean al millar más cercano, por lo que deben interpretarse como un indicador aproximado. El modo rápido tiene su propio grupo y sus propias cabeceras anthropic-fast-*. Lea todas las cabeceras en cualquier llamada correcta:

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'

Todas las respuestas también incluyen una cabecera request-id única, como req_018EeWyXxfu5pfWkrYcMdjWG. En los cuerpos de error aparece como request_id y en las respuestas de los SDK de Python y TypeScript, como _request_id. Inclúyala cuando contacte con soporte.

Antes de escribir un bucle de espera, compruebe si realmente necesita uno. Los SDK oficiales reintentan automáticamente los fallos transitorios, incluidos los errores de conexión, los límites de tasa y los errores del servidor 5xx, con una espera exponencial. De forma predeterminada, realizan dos reintentos y respetan la cabecera retry-after cuando está presente. Cada cliente acepta una opción de reintentos máximos para cambiar o desactivar 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 culpa tuya

Un 429 indica que enviaste solicitudes demasiado rápido. Un 529 overloaded_error indica que la API está temporalmente sobrecargada. Puede ocurrir cuando la API recibe mucho tráfico de todos los usuarios. No se debe a tu clave ni a tu código. Reintenta con retroceso exponencial. Los SDK ya lo aplican a las respuestas 5xx. Si el problema no desaparece, consulta status.claude.com. Un 500 api_error indica un error interno. Reintenta de la misma forma. Ninguno de los dos códigos es un límite de tasa.

Consulte sus propios límites en lugar de una tabla

En una suscripción, /usage es la pantalla importante. Muestra las barras de uso de su plan y un desglose de lo que las consumió. d o w permiten cambiar entre las últimas 24 horas y los últimos 7 días. Hay dos aspectos que debe tener en cuenta. El bloque Session muestra el uso de tokens de API y está destinado a usuarios de la API, por lo que los suscriptores pueden ignorar su importe en dólares. Los números proceden del historial de sesiones local de ese equipo. Por tanto, no incluyen el uso de otro dispositivo ni de claude.ai.

En la API, la página Usage de Claude Console muestra dos gráficos: "Rate Limit - Input Tokens" y "Rate Limit - Output Tokens". El gráfico de entrada representa el máximo horario de tokens de entrada no almacenados en caché por minuto frente a su límite ITPM actual. También muestra la tasa de caché, para que pueda supervisar la aproximación a un límite antes de alcanzarlo en producción.

Para consultar 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"

Se necesita una clave de API de Admin. GET /v1/organizations/workspaces/{workspace_id}/rate_limits hace lo mismo para cada espacio de trabajo. Ambas operaciones son de solo lectura. Para cambiar un límite, use la pestaña Limits de Console.

Usar menos para ajustarse a más límites

En ambos sistemas se mide lo mismo internamente, por lo que estos controles funcionan en cualquiera de los dos.

• Gaste menos tokens por turno. Las sesiones continuas mantienen la caché activa, y /clear entre tareas no relacionadas no tiene coste. El uso de tokens de Claude Code explica estos controles en detalle.
• Reduzca el nivel de esfuerzo. Los niveles son low, medium, high, xhigh y max. El menú /effort también ofrece ultracode, que aumenta el consumo en lugar de reducirlo. El razonamiento profundo no aporta nada para un cambio de nombre mecánico.
• Reduzca la concurrencia después de un 429. Disminuya CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY y evite muchos subagentes en paralelo. Ejecute también /status: un ANTHROPIC_API_KEY perdido dirige las solicitudes a una clave de nivel bajo en lugar de a su suscripción.
• Traslade el trabajo no interactivo a la Message Batches API. Ejecuta grandes volúmenes de forma asíncrona con un descuento del 50% en los tokens de entrada y salida, bajo sus propios límites de tasa. Así, una tarea nocturna deja de competir con su sesión.

El trabajo que introduce muchos datos en el contexto es el que más nota este efecto: si está analizando acciones y opciones con datos de mercado en tiempo real, extraer sólo el segmento que necesita cada pregunta cuesta una fracción de lo que cuesta pegar tablas completas de cotizaciones y cadenas de opciones. El trabajo en ráfagas dirigido por un programa, y no por una persona, debe usar una clave de API desde el principio. El traslado también cambia la forma de pago y de medición, porque Claude API no tiene un nivel gratuito más allá del pequeño crédito concedido al registrarse. Su primera aplicación de Claude API en un VPS explica la gestión de claves y los reintentos. Una ejecución larga del agente puede sobrevivir a una conexión interrumpida si mantiene Claude Code ejecutándose en un VPS dentro de tmux.

FAQ

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

Porque los límites de sesión y semanales se comparten entre todos los modelos. La cuota corresponde al plan, no a un modelo, por lo que /model cambia el modelo que respondería, pero no la cuota disponible. La única excepción es You've hit your Opus limit, que se aplica sólo 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 la cuenta alcanzó 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 una cabecera retry-after con los segundos que debe esperar, y los reintentos anteriores fallan. Los SDK oficiales ya reintentan los límites de tasa y los errores 5xx con retroceso exponencial, dos veces de forma predeterminada, respetando esa cabecera. Un 429 que aparece mientras todavía se encuentra dentro de los límites de su nivel indica un límite de aceleración debido a un aumento repentino.

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

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

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

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