Límites de velocidad en Claude Code: suscripción frente a API 429

Qué significa un límite de velocidad en Claude Code

Claude Code admite dos modos de autenticación fundamentalmente diferentes:

• Suscripción (Pro, Max, Team o Enterprise): inicio de sesión mediante OAuth de Claude.ai. Claude Code y las demás superficies de Claude consumen el fondo compartido del plan; consulta las ventanas actuales y restricciones adicionales en /usage y en la configuración de la cuenta.
• Clave de API (ANTHROPIC_API_KEY en el entorno): las solicitudes se envían directamente a api.anthropic.com. Los límites son RPM, ITPM y OTPM del nivel de tu espacio de trabajo en Anthropic Console.

Si ANTHROPIC_API_KEY está definido, tiene prioridad sobre la suscripción. Claude Code usará esa clave aunque hayas iniciado sesión con una suscripción; esta es una causa frecuente de confusión.

¿Necesitas saber si la solicitud llegó a un endpoint de terceros? BetterToken añade otra capa de diagnóstico: su Dashboard muestra el estado de la solicitud, el modelo, los tokens de entrada, salida y caché, y el cargo correspondiente. Así puedes separar un límite del proveedor de un error de Anthropic API. Consulta la documentación de BetterToken para configurar la Base URL y la clave de API, y compárala con tu flujo de trabajo actual.

Cómo identificar un límite de suscripción, de Anthropic API o de otro endpoint

Empieza ejecutando /status en Claude Code. Indica el método de autenticación actual —cuenta con suscripción o clave de API— y por tanto dónde investigar después.

• Suscripción Pro/Max/Team: /status muestra una suscripción y el mensaje cita un límite de sesión o semanal con hora de restablecimiento. El uso del plan se agotó; espera el restablecimiento y revisa /usage y, si existe, /usage-credits.
• Anthropic API 429: /status muestra una clave de API, existe ANTHROPIC_API_KEY y la respuesta contiene HTTP 429 o rate_limit_error. Se restringen RPM, ITPM u OTPM del nivel elegido. Revisa primero retry-after y reduce la concurrencia.
• Endpoint de terceros: se usa una Base URL personalizada y una clave del proveedor; el código y formato de respuesta pueden diferir de Anthropic. Lee primero la respuesta y revisa después la página de estado y las condiciones de cuota del proveedor.

Trata 500 api_error, 504 timeout_error y 529 overloaded_error por separado. Son errores de servidor o transitorios, no prueba de que se haya agotado la asignación de una suscripción. Usa un backoff exponencial limitado. Toda respuesta de Anthropic lleva request-id en un encabezado, y un error incluye también request_id en JSON; guarda ese identificador para soporte.

Diagnóstico paso a paso sin filtrar una clave de API

Paso 1. Comprobar el método de autenticación

En una sesión de Claude Code:

/status

Mira “Login method” o “Auth token”. Si está definida ANTHROPIC_API_KEY pero quieres usar la suscripción, elimina antes la variable:

unset ANTHROPIC_API_KEY

Reinicia Claude Code y vuelve a comprobar /status.

Paso 2. Leer el mensaje de error completo

El texto exacto es la señal principal: “Resets at [hora]” significa límite de suscripción; rate_limit_error con encabezado retry-after significa API 429 y requiere revisar Anthropic Console; api_error, timeout_error u overloaded_error son errores 5xx/529 transitorios para reintentar con backoff; un formato propio del proveedor más una Base URL no estándar apunta a un problema del proveedor.

Guarda un conjunto de diagnóstico seguro: hora, error.type, request-id/request_id, versión de Claude Code y endpoint seleccionado. No incluyas la clave de API, el encabezado Authorization ni el contenido de .env.

Paso 3. Comprobar el uso actual

Para una suscripción:

/usage

Muestra las barras de uso de Pro/Max: lo que queda antes de que se restablezca la ventana de cinco horas y antes del tope semanal. Cambiar de modelo con /model no recupera horas de cómputo ya consumidas; la asignación se comparte entre modelos.

Para la API, abre Anthropic Console → Settings → Limits. Allí verás el nivel, los límites actuales de RPM/ITPM/OTPM y el uso. Para BetterToken, abre el Dashboard y busca la solicitud por hora: puedes comprobar modelo, estado, tokens de entrada/salida/caché y cargo. El Dashboard confirma si la solicitud llegó a BetterToken, pero conserva por separado el identificador del cuerpo o los encabezados de respuesta.

Paso 4. Comprobar el estado oficial

https://status.anthropic.com/

Un incidente que afecte a Claude Code o a la API explica el problema con independencia de tus límites.

Paso 5. Comprobar conflictos de configuración

Definir a la vez ANTHROPIC_API_KEY y ANTHROPIC_BASE_URL puede producir un comportamiento inesperado. No mantengas dos conjuntos de variables para esquemas de autenticación distintos en el mismo entorno. Al pedir ayuda, nunca incluyas Authorization, x-api-key ni .env en registros o capturas; bastan el texto de error, código HTTP, claude --version y /status sin valores de claves.

Qué hacer después de identificar el origen

Límite de suscripción (Pro/Max/Team): espera el restablecimiento que indican /usage y el error. Si afecta a un modelo concreto, selecciona otro disponible con /model; esto no restablece el uso total del plan. Ejecuta /usage-credits si hay créditos de uso y usa /clear entre tareas no relacionadas para reiniciar el contexto y reducir el consumo posterior.

Anthropic API 429 (rate_limit_error): lee retry-after y espera el periodo indicado; reduce la concurrencia, pues varias tareas de agentes agotan RPM, ITPM y OTPM con mayor rapidez. Comprueba el nivel y los límites actuales en Anthropic Console → Settings → Limits, no cifras antiguas fijas. Para crecimiento sostenido, solicita un aumento de límites a Anthropic desde Console.

Endpoint de terceros: abre su página de estado, pregunta al proveedor por su cuota actual y formato de error, y cambia a Anthropic API directa u otro proveedor si es necesario.

5xx / 529: usa backoff exponencial limitado para 500, 504 y 529; el SDK oficial ya reintenta algunos errores transitorios. Revisa status.anthropic.com; si el error continúa, entrega al soporte request-id, hora y tipo de error, sin secretos.

Cuándo esperar, cambiar la carga o contactar con soporte

• Límite de suscripción con hora de restablecimiento: espera, cambia de modelo o usa /clear.
• API 429 con retry-after: espera el periodo indicado y reduce la concurrencia.
• API 429 frecuentes sin retry-after: comprueba el nivel y solicita un límite mayor si lo necesitas.
• 500 / 504 / 529: aplica backoff exponencial limitado, comprueba el estado del servicio y conserva request-id.
• Error de endpoint de terceros: contacta con ese proveedor.
• Límite no claro con suscripción activa: contacta con soporte de Claude.ai.
• Límite no claro con clave de API activa: contacta con soporte de Anthropic Console.

El soporte de suscripciones y el de API son equipos distintos. El equipo de Anthropic API Console no puede resolver un límite de suscripción Pro/Max, y viceversa.

Preguntas frecuentes

¿Por qué veo “rate limit” justo al iniciar una sesión?

Puede deberse a que (1) el entorno contiene ANTHROPIC_API_KEY de un nivel bajo, que tiene prioridad sobre la suscripción; compruébalo con /status; (2) una sesión anterior consumió gran parte de la ventana móvil, que no se restablece al reiniciar Claude Code; o (3) varios dispositivos o tareas de agentes usan la misma cuenta y se suma su uso.

¿Ayuda cambiar de modelo con /model?

En parte para las suscripciones. “You've hit your Opus limit” significa que se agotó la asignación de Opus; cambiar a Sonnet puede permitir continuar en la misma sesión. El presupuesto de cómputo compartido semanal y de cinco horas no se restaura al cambiar de modelo.

¿Debo incluir los registros completos al pedir ayuda?

No. Bastan el texto completo del error, código HTTP, salida de /status sin valores de claves, claude --version, hora y el estado de status.anthropic.com entonces.

¿Qué límites dinámicos cambian con más frecuencia?

Los límites de nivel de API (RPM, ITPM y OTPM) y los parámetros de las ventanas de suscripción pueden cambiar. Obtén los valores actuales solo de páginas oficiales:

• Costes y uso: code.claude.com/docs/en/costs
• Errores y límites de velocidad de API: platform.claude.com/docs/en/api/errors
• Estado del servicio: status.anthropic.com

No confíes en cifras de tutoriales o foros: quedan obsoletas rápidamente.