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 por puesto) incluye una cuota de uso móvil que se comparte entre los modelos, salvo algunos límites específicos de ciertas familias de modelos, y con Claude chat. Cuando se agota, aparece un mensaje como You've hit your session limit · resets 3:45pm. Los planes Enterprise actuales basados en el uso son la excepción: no incluyen ninguna cuota y todo el uso se factura con las tarifas de la API desde el primer token. 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, normalmente con una cabecera retry-after que indica cuántos segundos debe esperar.

Las soluciones no tienen nada en común. Un límite de suscripción depende de cuánto uso haya realizado dentro de una ventana. Debe esperar al restablecimiento, comprar más uso o utilizar un restablecimiento gratuito del límite si su plan ofrece esa opción. Un límite de velocidad de la API depende de la velocidad actual. Se elimina en unos segundos cuando reduce la velocidad de envío.

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 incluyen aquí. Consulte los valores de su cuenta con los comandos que aparecen más adelante.

¿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 agotado la asignación móvil de su plan para este periodo.
• You've hit your weekly limit · resets Mon 12:00am es el mismo sistema en el periodo más largo.
• 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. Cambiar a un modelo fuera de la familia Opus le permite seguir trabajando.
• You've hit your Sonnet limit · resets 3:45pm es el mismo tipo de límite de familia de modelos, pero sólo para las solicitudes de Sonnet. Cambiar a un modelo fuera de la familia Sonnet le permite seguir trabajando.
• Un mensaje que comienza por Fable limit reached significa que ha utilizado la parte de su asignación semanal que pueden consumir los modelos Fable. Continuar con Fable genera cargos por créditos de uso, por lo que Claude Code le pide confirmación antes. Elija otro modelo con /model para mantenerse dentro de su plan.
• 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 clave de API 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 del 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 que no está relacionada con la cuota de su plan. Claude Code reintenta automáticamente la solicitud con una espera progresiva antes de mostrarle esa línea.

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

Un plan Pro, Max, Team o Enterprise basado en puestos incluye una asignación de uso renovable. Cuando se agota, Claude Code bloquea las solicitudes adicionales hasta la hora de restablecimiento que se muestra en el mensaje. Dos propiedades de esa asignación causan la mayor parte de la confusión.

• Se comparte con Claude chat. El trabajo que realiza en claude.ai consume la misma asignación que el trabajo en la terminal, por lo que una tarde de uso intensivo 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 comparten una asignación, no tienen una cada una.
• Se comparte entre modelos. Los límites de sesión y semanales forman un único fondo para todos los modelos. Las excepciones son los límites por familia de modelos dentro de ese fondo: los límites de Opus y Sonnet, y, en los puestos Max y Premium, una asignación de Fable de hasta el 50% de los límites semanales. En los puestos Pro y Standard, Fable no está incluido en los límites del plan y se factura con créditos de uso desde la primera solicitud.

En Claude for Teams y Enterprise basado en puestos, el esquema documentado consiste en una asignación por puesto que se restablece en una ventana renovable de cinco horas y en una ventana semanal. Se comparte con Claude chat y Cowork, y su tamaño depende del nivel del puesto (Standard o Premium). Los planes Enterprise actuales basados en el uso funcionan de otra manera: no hay una asignación incluida que pueda agotarse, el uso se factura según las tarifas de la API y el límite es el que establezcan los administradores para el gasto de la organización y de cada usuario. En un plan con asistencia de ventas, el uso detenido por un límite de gasto se reanuda al comienzo del siguiente periodo de facturación, salvo que un propietario aumente antes el límite. En un plan de autoservicio, el uso también se detiene cuando se agota el saldo de créditos prepagados, hasta que un propietario compre más. En Pro y Max, la hora de restablecimiento que aparece en el mensaje y sus propias barras /usage son los datos fiables, no una cifra copiada de una entrada de blog. Si todavía está eligiendo un nivel, qué plan de Claude necesita compara las restricciones de cada uno.

Por qué cambiar de modelo con /model no restaura una sesión ni el límite semanal

Este es el error más común, y la documentación lo indica claramente: los límites de sesión y semanales se comparten entre todos los modelos, por lo que cambiar de modelo no restaura 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 disponible, porque las asignaciones de sesión y semanales no se mantienen por modelo y, por tanto, el cambio no libera nada.

Las excepciones son los límites por familia de modelos. Si el mensaje muestra You've hit your Opus limit o You've hit your Sonnet limit, /model es la solución correcta. Cambie a un modelo que no pertenezca a esa familia y siga trabajando, porque sólo se bloquearon las solicitudes de esa familia. El límite de Fable en las suscripciones Max y Premium funciona igual: cambie a otro modelo para seguir trabajando dentro de su plan o continúe usando Fable con créditos de uso. Sin embargo, Fable consume el grupo semanal compartido más rápido que otros modelos, por lo que cambiar de modelo después de alcanzar el límite de Fable nunca permite superar el límite semanal general.

Considerar que el límite es un error es el segundo paso equivocado. Reinstalar o volver a autenticarse no cambia nada. La asignación se restaura cuando se reinicia la ventana, cuando utiliza un restablecimiento de límite gratuito o cuando compra créditos de uso.

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

1. Consulte la hora del restablecimiento. Una ventana de sesión es corta. Una ventana semanal no se resuelve esperando frente al equipo. En Claude Code v2.1.234 o posterior, /rate-limit-options puede esperar al restablecimiento y continuar automáticamente la tarea interrumpida.
2. Si se trata del límite de Opus, Sonnet o Fable, ejecute /model y seleccione un modelo fuera de esa familia.
3. Ejecute /usage para consultar los límites de su plan, sus barras y cuándo se restablecen. /cost es un alias de la misma pantalla.
4. Compruebe Settings > Usage en claude.ai o en Claude Desktop para consultar la sección Resets. En ocasiones, los planes elegibles reciben una oferta de restablecimiento gratuito del límite. Al hacer clic en "Reset for free", el límite de sesión de cinco horas o el límite semanal, según cuál cubra la oferta, vuelve inmediatamente a su capacidad completa. El botón no está disponible en Claude Code desde un terminal o IDE, ni en Claude Mobile, y cada oferta caduca.
5. Ejecute /usage-credits para seguir trabajando después de alcanzar el límite. En Pro y Max, se abrirá la configuración de facturación. En Team y Enterprise, se abrirá la configuración de uso de su organización o se enviará una solicitud a los administradores si no tiene acceso a la facturación.
6. Si alcanza el mismo límite cada semana, el plan no se ajusta a su 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 requiere 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 forma predeterminada, Claude Code proporciona a la conversación principal una caché de indicaciones de una hora mientras se mantiene dentro del uso incluido en la suscripción. Cuando empieza a consumir créditos, la reduce a cinco minutos. Por eso, más turnos empiezan sin caché y aumenta el uso de tokens de Claude Code para el mismo trabajo. Los subagentes están fuera de ese grupo de la conversación principal, por lo que reciben cinco minutos incluso dentro del uso del plan. Si elige el TTL manualmente con el ajuste promptCacheTtl o CLAUDE_CODE_PROMPT_CACHE_TTL en Claude Code v2.1.242 o posterior, se mantiene la duración de una hora mientras consume créditos.

Los mensajes que parecen límites de uso, pero 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, seguida del comando que libera espacio, cuando la conversación supera la ventana de contexto del modelo. La compactación resume el historial antiguo para liberar espacio, pero no es gratuita: /compact lee la conversación que resume, por lo que compactar un contexto grande constituye una solicitud grande para su plan. Cuando quiera empezar de cero en lugar de conservar la continuidad, /clear no tiene ningún coste.
• Prompt is too long · automatic compaction failed: <the underlying error> significa que la compactación automática ha fallado por el error que indica. /compact seguirá fallando con ese mismo error hasta que lo resuelva.
• Credit balance is too low significa que su organización de Console ha agotado los créditos prepagados o que Claude Code está enviando las solicitudes de un suscriptor mediante una clave de API de Console; /status muestra qué credencial está activa. 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 (they take effect after you restart Claude Code), or /model to switch to standard context es una comprobación de derechos, no una cuota agotada. Si seleccionó una variante [1m] de Opus 4.6 o Sonnet 4.6, elija la variante sin el sufijo [1m] o establezca CLAUDE_CODE_DISABLE_1M_CONTEXT=1. Si aparece a mitad de una conversación porque el contexto superó los 200K tokens, Claude Code compacta el contexto por sí solo para volver a situarlo por debajo del límite estándar. Sonnet 5 y posteriores, Opus 4.7 y posteriores, Haiku 5.5 y los modelos Fable se ejecutan con una ventana nativa de 1M y no tienen ningún sufijo que quitar; esa variable es la que los limita a 200K.

Otro error procede de la API. Un 413 request_too_large es un límite de tamaño para una sola solicitud, no un límite de frecuencia.

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

La Messages API mide tres aspectos, 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. Es un valor distinto: el coste mensual máximo del 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, a menos que solicite un límite superior. También se devuelve como un 429 rate_limit_error, pero sin la cabecera retry-after y con enforced_spend_limit_reached en error.details.error_code. Ningún bucle de reintento resuelve este problema. Un límite de gasto inferior que configure usted mismo en la Console se muestra de otra forma: las solicitudes devuelven HTTP 400 invalid_request_error con un mensaje que empieza por You have reached your specified API usage limits, y aumentar o quitar el límite restaura el acceso.

Cuatro mecanismos determinan cuándo llega el 429.

• Los límites son por clase de modelo. Se aplican por separado a cada modelo, por lo que puede usar distintos modelos hasta sus límites respectivos al mismo tiempo. Algunas familias comparten un mismo bloque: el límite de tasa de Opus es total para Claude Opus 4.8, Opus 4.7, Opus 4.6 y Opus 4.5, mientras que Claude Sonnet 5 tiene su propio límite.
• La capacidad se repone de forma continua. La API utiliza un algoritmo de token bucket, por lo que la capacidad se repone de forma continua en lugar de reiniciarse en un momento fijo. Un límite de 60 solicitudes por minuto puede aplicarse como una solicitud por segundo, por lo que 60 solicitudes enviadas a la vez seguirán fallando.
• En la mayoría de los modelos, sólo la entrada no almacenada en caché cuenta 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, el almacenamiento en caché proporciona margen adicional para el límite de tasa, además de un descuento. En la salida, un max_tokens alto no cuenta para OTPM, porque OTPM sólo cuenta los tokens que se generan realmente.
• Los límites se aplican a nivel de organización. A un workspace se le puede asignar 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 workspaces sea superior. Si no ha sobrescrito un límite en un workspace, este se hereda de la organización; no queda sin límite.

Los niveles Start, Build, Scale y Custom establecen los valores reales. Se asignan automáticamente a partir de su historial de uso y del estado de su cuenta. Las organizaciones nuevas y las que tienen poco historial de uso pueden comenzar en el nivel Evaluation, por debajo de los límites estándar publicados, por lo que el primer 429 puede llegar antes de lo que indique una tabla. Un aumento brusco del uso activa límites de aceleración, que devuelven 429 aunque todavía se encuentre dentro de su nivel. Por eso, aumente el tráfico de forma gradual. Todas las cifras publicadas son valores máximos: los límites documentados representan el uso máximo permitido, no mínimos garantizados. Para solicitar un valor superior, use "Request tier increase" en la página Rate limits de Claude Console.

Interpretar un 429: retry-after, cabeceras y reintentos del SDK

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

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

Las cabeceras contienen el resto de la información.

• retry-after indica el número de segundos que debe esperar antes de volver a intentar la petición. Los reintentos anteriores fallarán. No todos los 429 incluyen esta cabecera, y el 429 por límite de gasto nunca la incluye.
• 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 para límite, cantidad restante y restablecimiento.
• anthropic-ratelimit-tokens-* muestra los valores del límite más restrictivo que esté vigente.

Las cabeceras de restablecimiento contienen marcas de tiempo RFC 3339. Las cabeceras de tokens restantes se redondean al millar más cercano, así que debe interpretarlas como un indicador aproximado. El modo rápido tiene su propio grupo y sus propias cabeceras anthropic-fast-*. Lea todas estas 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 progresiva, compruebe si realmente lo necesita. Los SDK oficiales reintentan automáticamente los fallos transitorios, incluidos los errores de conexión, los límites de solicitudes y los errores del servidor 5xx, mediante una espera progresiva exponencial. Lo hacen dos veces de forma predeterminada 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.

Lea 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 alterna entre las últimas 24 horas y los últimos 7 días. Hay dos consideraciones. El bloque Session muestra el uso de tokens de API y está pensado para 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 al límite ITPM actual. También muestra la tasa de caché. Así puede supervisar la aproximación al límite antes de alcanzarlo en producción.

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

Necesita credenciales de Admin API: una clave de Admin API, un token de OAuth con el ámbito org:admin, o una clave personal o de cuenta de servicio que no esté limitada a un workspace. Las claves de API de workspace no funcionan. GET /v1/organizations/workspaces/{workspace_id}/rate_limits hace lo mismo para cada workspace. Ambas operaciones son de solo lectura. Para cambiar un límite, use la página Rate limits de Console.

Usar menos para ajustarse a más límites

Ambos sistemas miden lo mismo internamente, por lo que estas medidas 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. Uso de tokens de Claude Code explica todas estas medidas.
• 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 en un cambio de nombre mecánico.
• Reduzca la concurrencia después de un 429. Disminuya CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY y evite ejecutar muchos subagentes en paralelo. Ejecute también /status: un ANTHROPIC_API_KEY olvidado puede enviar las solicitudes mediante una clave de nivel inferior en lugar de usar su suscripción.
• Traslade el trabajo no interactivo a la Message Batches API. Procesa grandes volúmenes de forma asíncrona con un descuento del 50% en los tokens de entrada y salida, y con sus propios límites de tasa. Así, una tarea nocturna deja de competir con su sesión.

Este problema se nota especialmente en los trabajos que cargan grandes cantidades de datos en el contexto: si está analizando acciones y opciones con datos de mercado en tiempo real, extraer sólo el intervalo 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 controlado por un programa, en lugar de por una persona, debe ejecutarse desde el principio con una clave de API. El cambio modifica tanto la forma de pago como la forma en que se aplican los límites, ya que la Claude API no tiene un nivel gratuito. Los planes Max y Team sí incluyen créditos mensuales de API para ejecutar sus propias aplicaciones y agentes después de vincular una organización de Console. Esos créditos no cubren Claude Code ni modifican los límites de uso del plan. Su primera aplicación de Claude API en un VPS explica la gestión de claves y los reintentos, y una ejecución larga de un agente puede continuar después de perder la conexión 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. Esa cuota pertenece al plan, no a un modelo, por lo que /model cambia el modelo que respondería, pero no la cuota disponible. Las excepciones son los límites por familia de modelos: You've hit your Opus limit y You've hit your Sonnet limit sólo se aplican a esa familia, y el límite de Fable en las suscripciones Max y Premium limita únicamente Fable. En esos casos, cambiar de modelo es la solución documentada.

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

Significa que la cuenta alcanzó un límite de frecuencia para esa clase de modelo: solicitudes por minuto, tokens de entrada por minuto o tokens de salida por minuto. La respuesta suele incluir una cabecera retry-after con los segundos que debe esperar, y los reintentos prematuros fallan. Los SDK oficiales ya reintentan los límites de frecuencia y los errores 5xx con retroceso exponencial, dos veces de forma predeterminada, y respetan esa cabecera cuando está presente. Un error 429 que llega mientras aún se encuentra dentro de los límites de su nivel indica un límite de aceleración provocado por un aumento repentino. Un error 429 con enforced_spend_limit_reached en error.details.error_code, que nunca incluye una cabecera retry-after, indica el límite de gasto mensual; esperar unos minutos no lo eliminará.

¿Cómo puedo consultar 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 permite cambiar entre las últimas 24 horas y los últimos 7 días. Esas cifras proceden del historial de sesiones local, por lo que no incluyen el uso de otros dispositivos ni de claude.ai. En la API, la Console muestra gráficos de los límites de frecuencia, y GET /v1/organizations/rate_limits devuelve los límites configurados con credenciales de Admin API, como una clave de Admin API.

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

A veces. Ejecute /usage-credits para comprar uso adicional por encima del límite 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, use un restablecimiento gratuito del límite si Settings > Usage en claude.ai o Claude Desktop ofrece esa opción, cambie de modelo si se alcanzó el límite de Opus, Sonnet o Fable, o traslade el trabajo a una clave de API, que mide el uso por minuto en lugar de por ventana.