Si Claude Code o una llamada a Claude API devuelve API Error: Rate limit reached, no empieces cambiando la key, comprando créditos o aumentando los retries. El texto visible solo dice que la solicitud fue bloqueada. La reparación depende de la ruta activa: Claude Code, API key, provider, créditos, modelo/contexto o estado de la plataforma.
| Dónde aparece el error | Qué mirar primero | Posible responsable | Siguiente paso |
|---|---|---|---|
| Claude Code en terminal o editor | /status, cuenta, plan, ANTHROPIC_API_KEY | Uso de Claude Code, login de suscripción, API-key override, contexto | Mantén la misma sesión, confirma la ruta y luego espera, reautentica o cambia de forma explícita a API |
| SDK, curl o logs con HTTP 429 | API key, organization, project, model, headers, Console Limits | Límite de Anthropic API por key, proyecto, modelo o tokens | Reintenta solo si la presión de requests o tokens está demostrada |
| Gateway, cloud, hosted app o provider | Dashboard del provider, upstream body, provider request id | Quota del provider, wrapper throttle, project equivocado, upstream limit | Diagnostica el provider antes de aplicar consejos de direct API |
| Console muestra credits, billing o spend cap | Credits, billing, usage, spend configuration | Financiación o estado de cuenta | Detén retries hasta cambiar el estado de la cuenta |
| Solo falla un modelo o un contexto largo | Model, context length, token volume, concurrency | Presión de model family o contexto | Reduce contexto, limita output, baja concurrencia o prueba un modelo menor |
| Varias rutas fallan a la vez | Claude Status, timestamp, request id, recent changes | Incidente o degradación | Guarda evidencia y espera, sin mover cuentas a ciegas |
La regla de parada es sencilla: retry solo es correcto cuando la evidencia apunta a presión de requests o tokens y existe reset, header, Console signal, Rate Limits API o provider signal. Si la evidencia apunta a credits, billing, wrong project, wrong key, Claude Code allowance, provider quota o status incident, repetir la misma solicitud no arregla nada.
Secuencia de recuperación en diez minutos
Primero guarda el error exacto. Incluye HTTP status, error type, error code, request id, endpoint, model, timestamp y timezone. En Claude Code guarda el texto de terminal y /status; en API guarda response body y headers; en provider guarda provider request id y upstream body si existe.
Después fija la superficie activa. Claude Code, direct Anthropic API, provider, Bedrock, Vertex y gateway pueden mostrar textos parecidos, pero no pertenecen al mismo contrato. No cambies model, key, provider y retry policy al mismo tiempo: si una prueba pasa, no sabrás qué variable importó.
El tercer paso es el scope. Una key nueva del mismo project no arregla un project-level limit. Un modelo pequeño no arregla billing. Un retry loop no arregla una ventana de Claude Code. También confirma que el project que miras en Console es el que realmente usa el proceso.
El cuarto paso es una prueba mínima en la misma ruta. En Claude Code, un comando corto en la misma sesión después de /status. En API, una solicitud pequeña con la misma key y model después de leer headers. En provider, una solicitud mínima por la misma ruta y el log del provider. El objetivo es demostrar la rama, no esperar un éxito accidental.
Lee bien la evidencia del límite API
Los límites de Anthropic API no son un solo número. Se separan por request rate, input tokens y output tokens. En Messages API importan RPM, ITPM y OTPM. Pocas solicitudes con contextos largos pueden chocar con token limits aunque el número de requests parezca bajo.
Cuando la ruta API-key está confirmada, la evidencia viva pesa más que una tabla vieja. Mira response headers, retry-after, Console Limits, Usage, Billing y Rate Limits API. No presupuestes producción con un RPM universal salvo que venga de la cuenta, proyecto, modelo y momento actual.
| Evidencia | Significado | Primera reparación |
|---|---|---|
| Headers o Console muestran request pressure | Demasiadas solicitudes en la ventana activa | Backoff con jitter, menos concurrencia, cola por tenant |
| Domina presión de input/output tokens | Contexto o generación demasiado grande | Reducir contexto, limitar output, partir tarea, usar caching donde encaje |
| Solo falla un model o family | Límite de model family o del modelo elegido | Probar modelo menor, bajar carga, esperar reset |
El backoff debe tener límites. Si el cliente expone retry-after, úsalo. Si no, usa exponential backoff with jitter y un máximo de intentos. Un retry infinito aumenta tráfico fallido y oculta el propietario real del problema.
Separa Claude Code del API directo
Claude Code puede parecer direct API, pero puede usar subscription login, API-key override, variables de equipo o provider credentials. Ejecuta /status antes de asumir que el plan Pro/Max o la API key explican el error.
Si la sesión usa subscription login, revisa usage, selected model, context size y sesiones paralelas. Una sesión larga de coding acumula summaries, tool outputs y decisiones anteriores. /compact, una nueva sesión, un modelo menor o menos paralelismo pueden ser pruebas válidas, pero no conviertas el contexto largo en explicación universal.
Si la sesión usa API key, trata el caso como problema de API. Revisa ANTHROPIC_API_KEY, shell profile, project env, CI variables y provider credentials. Un terminal local puede usar una key y un contenedor remoto otra. Si miras un project distinto al que usa el proceso, los créditos y limits parecerán contradictorios.
No uses extracción de tokens, OAuth workaround ni proxies aleatorios para evitar límites de Claude Code. Hacen más difícil demostrar la ruta, mueven secrets a lugares inseguros y pueden romper el comportamiento esperado. Las acciones seguras son esperar, reducir carga, corregir login o pasar explícitamente a una ruta API que puedas pagar y monitorizar.
Créditos, billing y propiedad de key
Credits y billing se confunden con rate limits porque la experiencia es la misma: la solicitud se bloquea. La reparación no es la misma. Si Console muestra low credits, billing issue, spend cap o account state, detén retries hasta cambiar ese estado.
Una key pertenece a organization y project. Un provider puede tener su propia quota, billing y throttle. En tickets registra identificadores seguros: organization, project, provider, environment source y deployment. No pegues API keys, bearer tokens ni session tokens.
La suscripción de Claude y el uso de API son contratos separados. Pro/Max puede influir en el uso de productos Claude y en el login de Claude Code, pero no se convierte automáticamente en una billetera de créditos API. Antes de comprar credits, demuestra que la rama activa es API funding o billing.
Provider, cloud y status
Bedrock, Vertex AI, gateways, hosted apps y proxies internos pueden tener quota, project selection, throttle, model mapping y error wrapping propios. El upstream Anthropic error body ayuda, pero no prueba que la cuenta direct Anthropic esté agotada.
En provider route, pregunta tres cosas: si el dashboard muestra quota o billing block local, si el log contiene upstream Anthropic request id o solo provider id, y si la misma solicitud pequeña falla con direct Anthropic credentials. Esas respuestas separan provider-owned issue, direct API issue y throttling de tu aplicación.
Claude Status es una rama aparte. Si varias rutas fallan a la vez, si suben los errores sin deploy o si varios usuarios reportan lo mismo, el status puede justificar esperar. Un status verde no prueba que tu key, project, provider, model o sesión de Claude Code esté sana.
Evidencia para soporte y prevención
Un paquete útil para soporte es breve: timestamp con timezone, exact error body, HTTP status, request id, active route, model, endpoint, identificadores seguros de org/project, headers, Console/provider limit state, Claude Status state y cambios recientes. No incluye secrets.
En producción, añade colas por tenant, límites de concurrencia por model family, logs de route/project/model/request id/token counts y alertas de credits/spend cap. En equipos que usan Claude Code, registra si la sesión es subscription-authenticated o API-key-authenticated. En provider, guarda provider id y upstream id juntos.
El objetivo no es prometer que nunca habrá límites. El objetivo es saber qué ruta falló, qué evidencia lo demuestra, si retry es seguro y qué propietario debe cambiar estado antes de que la siguiente solicitud funcione.
Checklist operativo para equipos
Un equipo debería fijar seis campos en su incident template: active route, credential source, model/context, live limit evidence, retry decision y support packet. Si falta uno, la conclusión “es rate limit” sigue incompleta.
CI, contenedores remotos y terminal local pueden cargar credenciales distintas. Un /status local sano no prueba que production use la misma ruta. Un startup log con un safe route summary, sin secrets, reduce incidentes repetidos.
Cuando el error se repite, compara patrones. Si siempre aparece con contextos largos, el arreglo está en compaction, output caps y session hygiene. Si siempre aparece en provider, hacen falta alertas del provider dashboard. Si siempre se confunden subscription y API key, imprime la ruta activa antes de iniciar cargas costosas.
Preguntas frecuentes
¿Debo reintentar de inmediato?
Solo si está demostrada la presión de requests o tokens y tienes reset, header, Console o provider signal. Si la causa es credits, billing, wrong project, wrong key, Claude Code allowance, provider quota o status incident, detén retries.
¿Por qué Claude Code muestra límite si tengo Pro o Max?
Claude Code puede usar subscription login o API key route. Ejecuta /status y revisa ANTHROPIC_API_KEY. Una suscripción no demuestra que la CLI no esté usando facturación API.
¿Comprar créditos API lo arregla?
Solo si la rama activa es API funding o billing. No arregla una ventana de Claude Code, wrong login, provider quota, long context pressure o platform incident.
¿Puede causarlo un contexto largo?
Sí, si la rama activa es token pressure, model family o session shape. Verifica model, context length, token volume, concurrency y una prueba con modelo menor.
¿Qué pasa si solo falla por provider?
Mira dashboard y logs del provider. Puede existir quota, project, billing, throttle o model mapping separado. Si hay upstream request id, guarda también provider id.
¿Qué envío a soporte?
Timestamp, timezone, exact error body, HTTP status, request id, active route, model, endpoint, safe org/project identifiers, relevant headers, Console/provider state, status state y recent changes. No envíes secrets.
