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

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. Guardar el estado en Git: Cree una rama temporal con los cambios pendientes:

git checkout -b task/pause-checkpoint
git add -A
git commit -m "checkpoint: guardado de estado antes del reinicio"

2. Crear archivo de traspaso (HANDOFF.md): Documente los hitos completados, las tareas pendientes y los archivos modificados. Esto permitirá a una sesión posterior retomar el trabajo sin releer todo el repositorio.

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.

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.