Claude Code muestra 50% pero avisa de límite semanal: Qué verificar

Los desarrolladores que utilizan Claude Code en la terminal a menudo se encuentran con un comportamiento desconcertante: el indicador local señala que la sesión o ventana de contexto está solo al 50%, pero la herramienta muestra una advertencia como Approaching Weekly Usage Limit o interrumpe la ejecución. Esta aparente contradicción se debe a la diferencia entre capas de monitorización: el porcentaje local mide el tamaño de la sesión activa, mientras que el servidor en la nube controla el límite semanal acumulado de la suscripción. En esta guía explicamos cómo diagnosticar el problema, guardar el trabajo en curso y evitar la pérdida de contexto.

Diferencias entre contadores: Ventana de contexto vs Límite semanal

Para comprender lo que ocurre, es necesario distinguir tres métricas independientes:

1. Indicador de sesión (Context Window): Muestra cuántos tokens del total permitido en la sesión actual (por ejemplo, 200k tokens) están ocupados por el historial, las instrucciones del sistema y los archivos leídos. Un 50% solo significa que le queda la mitad de espacio en esa sesión concreta.
2. Límite semanal acumulado del plan: Restricción sobre el volumen total de cómputo permitido en su suscripción durante un período móvil de 7 días. Si ha realizado tareas intensivas recientemente, la cuota semanal puede agotarse aunque la sesión actual esté casi vacía.
3. Límites de API y saldo de tokens: Al conectarse directamente mediante clave API, rigen los límites de peticiones por minuto (RPM/TPM) y el saldo disponible en cuenta.

Cuando el desarrollo en terminal requiere acceso ininterrumpido sin depender de los límites de planes web, los ingenieros recurren a pasarelas API con clave propia. Por ejemplo, mediante BetterToken, puede conectar modelos de programación con tarifas claras de pago por uso. La documentación detallada para configurar claves API externas está disponible en BetterToken Docs.

Diagnóstico y verificación del estado de la cuota

Ante un aviso de límite, evite reenviar peticiones de forma compulsiva para no prolongar bloqueos temporales. Siga estos pasos:

Paso 1: Registrar el mensaje de error exacto

Revise la salida en su terminal:

• Approaching weekly usage limit: Notificación preventiva de que el límite de 7 días está próximo a alcanzarse.
• You have reached your usage limit: Bloqueo total de nuevas peticiones hasta el reinicio de la ventana móvil.
• HTTP 429 Too Many Requests: Exceso puntual de frecuencia de llamadas o saldo de API agotado.

Paso 2: Consultar el panel de control web

Acceda a la sección de estadísticas en la consola web de su proveedor:

• Verifique la fecha y hora exacta del próximo reinicio de cuota (Reset Time).
• Revise la distribución de consumo diario para identificar picos de uso.

Cuándo pausar la tarea y cómo generar un handoff seguro

Si la cuota semanal está casi agotada, continuar con una refactorización compleja es arriesgado, ya que la sesión podría cortarse a la mitad.

Aplique este protocolo de seguridad (Handoff):

1. Inspeccionar el workspace sin preparar todo: Registre los archivos modificados y no seguidos antes de decidir si necesita un checkpoint:

git status --short
git diff --check

No use una orden de staging global. Cree un commit solo si forma parte de su proceso y después de revisar una lista explícita; en caso contrario, guarde un diff limitado y el handoff en una ubicación autorizada sin borrar cambios locales.

2. Crear archivo de traspaso (HANDOFF.md): Registre tarea, revisión, archivos exactos, comprobaciones superadas, restricciones y siguiente paso, sin copiar todo el transcript.

3. Cerrar la sesión activa: Termine el proceso en la terminal para evitar reintentos automáticos en segundo plano.

Suscripción web vs Pasarela API: Circuitos diferentes

Un error habitual es recargar saldo de API esperando que elimine el límite del plan web en Claude Code, o viceversa.

Parámetro	Suscripción Web (Plan)	Pasarela API Directa
Modelo de cuota	Tarifa fija con límites móviles por período.	Pago por tokens reales consumidos (Pay-as-you-go).
Comportamiento al agotarse	Bloqueo hasta la fecha de reinicio automático.	Pausa solo si el saldo llega a cero o se supera RPM.
Gestión del gasto	No permite comprar tokens adicionales sobre el plan.	Recarga de saldo flexible según las necesidades.

Comprender esta diferencia permite diseñar un flujo de trabajo óptimo: suscripción básica para consultas diarias y pasarela API dedicada para proyectos extensos.