Cuando Claude Code muestra que el límite de uso se ha alcanzado, la reacción más cara suele ser actuar demasiado rápido. Subir de plan, reabrir una tarea enorme, cambiar de cuenta o comprar créditos sin saber qué se agotó puede resolver nada y además complicar la sesión. El mensaje solo dice que la ruta actual chocó con una frontera. Esa frontera puede ser la ventana móvil de 5 horas, un límite semanal, una restricción de modelo, una política de organización, el uso adicional de un plan de pago, una cuota de API o un rate limit.
La respuesta útil empieza con una rutina breve: guarda el estado, ejecuta /usage, ejecuta /status, anota el reset time si aparece y confirma si ANTHROPIC_API_KEY está dirigiendo la sesión por API. Solo después conviene elegir entre esperar, compactar el contexto, dividir la tarea, subir a Pro / Max, activar uso adicional o pasar el trabajo a una integración API.
Los primeros cinco minutos
Primero evita agrandar el contexto. No le pidas a Claude Code que vuelva a leer todo el proyecto, que repita una reparación larga o que ejecute otra ronda grande de herramientas. En una sesión de código, cada lectura de archivo, salida de terminal, log de test, diff o búsqueda puede quedarse en el contexto. Aunque tu último mensaje sea corto, la petición real puede estar cargada de todo lo anterior.
Luego conserva la escena. Guarda los cambios, apunta el comando que falló, el texto exacto del error, el modelo, la hora aproximada, el reset time y la salida relevante de /usage. Si más tarde contactas con soporte o intentas reconstruir lo ocurrido, una captura con “usage limit reached” no basta. Necesitas saber si era una frontera de suscripción, API, organización o contexto.
Después decide una acción reversible. Si hay un reset claro y no hay urgencia, esperar es el camino con menos riesgo. Si el contexto está pesado, compactar o dividir en una nueva sesión puede ser mejor. Si hay una API key implicada, corrige la ruta API antes de tocar la suscripción. Si el bloqueo se repite y /usage confirma que el cuello de botella es el plan interactivo, entonces sí tiene sentido estudiar Pro / Max o uso adicional.
Qué puede significar el mensaje
En búsquedas en español aparecen varias promesas mezcladas: “cuándo se reinicia”, “cómo evitar el límite”, “por qué se consume tan rápido”, “Claude Code alcanza su límite” y “cómo sacar más partido”. El lector no necesita una explicación genérica de todos los límites de Claude. Necesita saber qué límite le está afectando en ese momento y qué acción no va a empeorar el trabajo.
| Síntoma visible | Frontera probable | Qué comprobar | Acción segura |
|---|---|---|---|
| El aviso muestra una hora de reinicio | ventana móvil de 5 horas | /usage y reset time | guardar el trabajo y esperar o seguir con una tarea pequeña |
| Se agota varias veces en el mismo día | límite semanal o sesiones pesadas | información semanal en /usage, patrón de trabajo | reducir sesiones largas y salidas de herramientas |
| Parece un rate limit o quota de API | ruta API | ANTHROPIC_API_KEY, billing, Console usage | corregir API, no subir la suscripción primero |
| Le pasa a varios miembros del equipo | organización o asiento compartido | configuración de admin, seat, usage de organización | revisar con quien administra el workspace |
| Una tarea grande consume todo de golpe | contexto grande o modelo costoso | /status, modelo, archivos y logs recientes | dividir, compactar en frontera de etapa, bajar el ruido |
La documentación de Anthropic describe los límites de uso como una especie de presupuesto de interacción durante un período. En Claude Code, las páginas oficiales separan Pro / Max, planes de organización, uso adicional y API keys. Por eso la pregunta correcta no es “qué plan compra más tiempo”, sino “qué ruta está bloqueada ahora mismo”.
La actualización de mayo de 2026 cambia el diagnóstico viejo
Durante 2026 circularon muchas explicaciones sobre límites más estrictos en horas pico, consumo anómalo y problemas de caché. Esas historias pueden servir para entender el contexto, pero no deben ser la primera explicación hoy. El 6 de mayo de 2026 Anthropic anunció que aumentaba los límites de cinco horas de Claude Code y eliminaba las reducciones de horas pico para usuarios Pro y Max.
Eso no significa que ya no existan límites. Siguen existiendo ventanas móviles, límites semanales, diferencias entre modelos, políticas de organización, rate limits de API y el coste de las sesiones largas. Lo que cambia es la hipótesis inicial: no conviene abrir con “me recortaron por hora pico” si la CLI no lo demuestra. La salida actual de /usage, /status y las páginas oficiales deben pesar más que los relatos antiguos.
Para una persona que programa, esta distinción evita dos errores comunes. El primero es esperar cuando el problema real está en una API key o en billing. El segundo es pagar más cuando el problema real es un contexto inflado por logs, archivos enormes y órdenes demasiado amplias. La solución correcta depende de la frontera, no de la palabra “límite” aislada.
Comprobaciones en orden
Empieza por /usage. No mires solo un porcentaje. Busca si el bloqueo se refiere a una ventana de sesión, al uso semanal, a un modelo, a un plan o a una indicación de reinicio. Si aparece una hora de reset, anótala. La ventana de cinco horas no se reinicia necesariamente a medianoche; el uso vuelve a liberarse cuando los mensajes salen de la ventana móvil.
Sigue con /status. Esta comprobación te dice cómo está conectada la sesión, qué modelo se está usando y qué ruta parece activa. Es frecuente creer que se está usando la suscripción Pro / Max cuando la shell tiene una ANTHROPIC_API_KEY que mueve el trabajo a la API. También puede pasar lo contrario: esperar comportamiento de API cuando la sesión sigue atada al producto de suscripción.
Revisa el entorno. ANTHROPIC_API_KEY no es malo por sí mismo, pero cambia el conjunto de límites que tienes que mirar. La suscripción y la API no son la misma bolsa. Un saldo API no arregla una ventana de suscripción agotada, y una suscripción más cara no arregla un rate limit de API mal gestionado.
Por último, mira la forma de la tarea. ¿Le pediste a Claude Code que leyera logs largos, un lockfile, varios archivos grandes, una traza completa o todo el repositorio? ¿Hubo varias rondas de pruebas con salida extensa? Entonces el aviso puede ser una consecuencia normal de una sesión pesada, no necesariamente una anomalía de cuenta.
Qué hacer después
Esperar es razonable cuando hay reset time y el trabajo no es urgente. Antes de parar, deja una nota de reentrada: archivos modificados, comando que falló, hipótesis pendiente y próximo paso mínimo. Cuando vuelva el uso, reinicia con una petición pequeña. “Sigue con todo lo anterior” suele ser peor que “revisa este archivo y este test”.
Compactar o dividir sirve cuando el problema principal es el tamaño de contexto. El momento bueno es un cierre de etapa: ya se encontró la causa, ya hay un diff manejable o ya se sabe qué test ejecutar. El momento malo es una investigación a medias. Si compactas ahí, puedes perder matices y gastar más uso repitiendo la investigación. Primero pide un handoff: qué se cambió, por qué, qué falta y qué no se debe tocar.
Subir a Pro / Max tiene sentido si el uso interactivo de Claude Code es tu cuello de botella repetido y demostrado. No sirve para arreglar un API 429, una variable de entorno equivocada, un problema de organización o una tarea gigantesca mal acotada. Antes de pagar más, comprueba que la frontera bloqueada es la suscripción.
El uso adicional es un puente cuando ya agotaste lo incluido en un plan de pago y necesitas continuar. Úsalo con conciencia de coste. No es un modo infinito gratuito ni una solución universal para API. Revisa cómo se cobra, qué saldo usa y dónde verás el consumo antes de activarlo como hábito.
La API es la mejor ruta para automatización, CI, herramientas internas, análisis por lotes y procesos que necesitan logs y presupuestos claros. Tiene sus propios límites y costes, pero permite diseñar reintentos, límites de concurrencia y alertas. Para conversación interactiva con una base de código, la suscripción puede ser más cómoda; para un flujo repetible, la API suele ser más honesta.
Por qué una sesión de código agota antes el límite
Claude Code no funciona como una conversación ligera. Lee archivos, ejecuta comandos, interpreta errores, mantiene decisiones previas y compara diffs. Esa capacidad aumenta el valor de la herramienta, pero también el volumen de información que el modelo debe tener presente.
Por eso un mensaje corto al final de la sesión no equivale a una petición barata. Si antes se leyeron varios archivos, logs y resultados de tests, la siguiente respuesta se apoya en ese historial. La sensación del usuario puede ser “envié una frase y se agotó todo”, pero la realidad puede ser “la sesión llevaba mucho contexto acumulado y esa frase fue el último paso”.
También importa el modelo. Un modelo más fuerte puede ser necesario para arquitectura compleja, bugs con varias capas o refactors grandes. Pero no todas las tareas merecen el mismo peso. Revisar un comando, resumir un error o comprobar un archivo pequeño puede hacerse con una sesión más acotada. La forma de trabajo pesa tanto como el plan contratado.
Cómo reducir interrupciones
Empieza cada tarea con un contrato pequeño. Define objetivo, archivos permitidos, comando de verificación, cosas que no se deben cambiar y condición de parada. En vez de “mira todo el proyecto y arréglalo”, pide “investiga este fallo dentro de este módulo y dime si necesitas ampliar el alcance”. Ese cambio reduce contexto innecesario y hace más fácil ver cuándo la tarea se está desbordando.
Divide el trabajo en investigación, cambio mínimo, prueba, ajuste y cierre. Al final de cada etapa, deja un handoff. Un buen handoff contiene archivos tocados, razón del cambio, prueba ejecutada, resultado, riesgos y siguiente paso. Si el límite aparece, ese paquete permite continuar más tarde sin arrastrar toda la conversación anterior.
Reduce salidas ruidosas. Un log completo de build, un JSON enorme o una traza de cientos de líneas no siempre son necesarios. Empieza con el comando y las líneas cercanas al error. Si eso no alcanza, amplía. Claude Code puede manejar material grande, pero el material grande debe responder a una pregunta precisa.
Cuándo subir de plan, usar extra usage o pasar a API
Sube de plan si tu trabajo principal es interactivo, diario y largo dentro de Claude Code, y si /usage demuestra que el límite de suscripción es la frontera habitual. No subas solo por un incidente. Mira varios días de patrón y corrige primero sesiones demasiado grandes.
Usa extra usage cuando una tarea importante está casi terminada y el reset te bloquea en un momento caro. Es útil como puente, no como sustituto de presupuesto. Si dependes de extra usage todos los días, revisa el plan, la forma de trabajo o la posibilidad de mover partes a API.
Pasa a API cuando el flujo sea programático. CI, batch, herramientas internas y agentes de proceso largo necesitan control de coste, logs, reintentos y límites de concurrencia. La API no elimina las restricciones, pero las vuelve visibles y manejables para un equipo técnico.
Preguntas frecuentes
Si aparece reset time, ¿solo puedo esperar?
No necesariamente. Esperar es lo más seguro, pero si la tarea es urgente puedes evaluar extra usage, un plan superior o API. La condición es comprobar primero que esa opción sirve para la ruta que está bloqueada. Si no sabes la ruta, cualquier pago es una apuesta.
¿Por qué /usage dice que queda uso y aun así se bloquea?
Puede estar actuando otra frontera: modelo, límite semanal, organización, API rate limit, billing o una variable de entorno. /usage abre la investigación; /status, el entorno y el texto completo del error la completan.
¿Pro / Max y API credits son lo mismo?
No. Pro / Max pertenecen al producto de suscripción. API credits pertenecen a la ruta API. Claude Code puede usarse en contextos donde ambas cosas existen, pero no forman una sola bolsa. Antes de comprar o subir de plan, confirma qué ruta usa la sesión.
¿Compactar contexto puede romper la investigación?
Puede, si se hace en medio de un problema complejo. La forma segura es pedir primero un handoff con estado, archivos, hipótesis, evidencia y próximo paso. Después compactas o abres una sesión más pequeña. La compactación reduce coste, pero no reemplaza una buena transferencia de estado.
¿Debo asumir que es el problema de caché de marzo de 2026?
No como primera hipótesis. Si sospechas consumo anómalo, registra hora, modelo, comandos, cambio en usage y texto del error. Para decidir hoy, usa la documentación actual y tu salida de CLI antes que explicaciones antiguas.
¿Necesito una herramienta externa de monitoreo?
Si el bloqueo es ocasional, las herramientas internas bastan. Si usas Claude Code muchas horas al día, un analizador local de logs puede mostrar qué proyectos y hábitos consumen más. Evita herramientas que pidan subir código privado o claves a un servicio no confiable.
Fuentes oficiales a revisar
Los límites y las opciones de pago cambian, así que las afirmaciones sensibles deben comprobarse con fuentes primarias. Revisa las páginas de Anthropic Help Center sobre modelos, uso y límites en Claude Code, límites de uso y duración, Claude Code con Pro o Max, uso adicional en planes de pago y el anuncio de Anthropic del 6 de mayo de 2026 sobre mayores límites de Claude Code.