Cuando Claude Code muestra API Error: Rate limit reached, no empieces por asumir que necesitas otro plan. Primero identifica la ruta de autenticación, revisa el uso y el reinicio que muestra el producto, separa los límites de API key o proveedor cloud, y comprueba si el contexto o los reintentos están haciendo que cada tarea sea demasiado pesada.
Respuesta rápida
- Si entras con una cuenta Claude o Enterprise, usa la pantalla actual de uso y reinicio de esa cuenta u organización.
- Si usas API key, ejecuta
/costy revisa Claude Console, Bedrock, Vertex o Microsoft Foundry para límites, gasto yretry-after. - Si la tarea es grande, usa
/compact,/clear, archivos más concretos y un modelo más ligero cuando/modello permita. - Si el uso visible no explica el bloqueo, refresca credenciales, reinicia la sesión, busca procesos en segundo plano y prepara evidencia antes de escalar.
Identifica quién posee el límite
Claude Code puede estar limitado por tres superficies distintas: la ventana de uso de una cuenta Claude o Enterprise, los límites de una API key o proveedor cloud, o el estado local de la sesión. Ejecuta:
bash/model /cost claude --version
/model muestra las rutas disponibles hoy para tu cuenta. /cost es relevante cuando trabajas con facturación API. claude --version ayuda si necesitas reportar un caso reproducible. No uses tablas antiguas de horas, precios o capacidad como contrato vivo.
Recuperación inmediata
Cambia a una ruta más ligera si está disponible. Usa /model para ver opciones reales. Ediciones pequeñas, formato, preguntas de sintaxis y resúmenes no siempre necesitan la ruta más pesada.
Limpia contexto. Usa /clear al cambiar de tarea. Usa /compact cuando necesitas conservar una conversación larga pero evitar que todo el historial siga creciendo.
Reduce el alcance de archivos. Pide revisar rutas concretas en lugar de todo el repositorio. Las lecturas de archivos, búsquedas, logs y salidas de pruebas se convierten en contexto para llamadas posteriores.
Respeta retry-after. En API o proveedor cloud, los headers y el dashboard actual son más fiables que cualquier número de un artículo antiguo.
Por qué una sesión corta también puede limitarse
Claude chat suele ser una interacción directa de pregunta y respuesta. Claude Code es un sistema agente que lee archivos, busca, ejecuta comandos, escribe cambios y corre pruebas. Una sola solicitud visible puede activar varios pasos de herramienta y llamadas de modelo.
La pregunta correcta no es solo "cuántos minutos usé", sino "cuánto contexto generó esta sesión". Archivos CLAUDE.md demasiado largos, búsquedas amplias, logs extensos, pruebas fallidas repetidas, subagentes y conversaciones viejas aumentan la presión sobre cada llamada posterior.
Cómo reducir consumo
Mantén CLAUDE.md estable y conciso. Si tu ruta actual se beneficia de prompt caching, verifica el contrato vigente en la documentación de Anthropic antes de planificar capacidad con números fijos.
Agrupa preguntas relacionadas en un solo prompt estructurado. Cinco preguntas pequeñas transmiten el mismo contexto varias veces.
Guarda explicaciones largas en archivos locales y referencia esos archivos después. No pidas al modelo que reanalice el mismo código una y otra vez.
Elige la ruta según el riesgo de la tarea. Usa rutas ligeras para trabajo simple y rutas más fuertes para cambios de alto riesgo, siempre con la lista actual de /model.
Falsos límites y escalación
Si el panel de uso y el error no coinciden, recopila evidencia: versión de CLI, ruta de autenticación, salida de /model, salida de /cost si aplica, pantalla de uso/reinicio, mensaje exacto y hora del incidente. Prueba cerrar sesión, volver a entrar y usar una sesión limpia antes de asumir que es un bug de plataforma.
Mientras esperas el reset
Puedes seguir trabajando sin la ruta bloqueada: escribir pruebas, reducir logs, preparar un contexto limpio, dividir la siguiente tarea, revisar PRs o actualizar documentación. Si usas otra herramienta de código como respaldo, verifica antes su cuota, ruta de modelo, política de datos y facturación.
FAQ
¿Cuánto tarda en recuperarse el límite?
Depende de la superficie que lo posee. Usa el reset mostrado por Claude Code o tu cuenta; para API, usa headers, Console o el dashboard del proveedor.
¿Vale la pena actualizar el plan?
Evalúalo solo después de reducir contexto, cambiar modelo de forma razonable y descartar falsos límites. Usa los precios actuales de tu cuenta, tu coste real de espera y si API o Enterprise encajan mejor.
¿Por qué Claude Code consume más que Claude chat?
Porque Claude Code ejecuta herramientas. Lecturas, búsquedas, comandos, escrituras y pruebas añaden contexto y llamadas; chat suele ser una pregunta-respuesta directa.