Si Claude muestra "Rate Exceeded", "Claude Error: Rate limit reached" o una línea 429 en Claude Code, no asumas que se agotó una sola cuota de API. Primero identifica la superficie: Claude.ai/Desktop usage window, Claude Code con suscripción, Claude Code con API key, Anthropic API directo, Bedrock/Vertex AI, gateway o capacidad temporal. Cada superficie tiene una señal de reset y un propietario distinto.
| Surface | Owner | First move | Proof | Next step |
|---|---|---|---|---|
| Claude.ai / Desktop / mobile | Usage window or capacity management | Revisa Settings > Usage, reduce chats/files largos | 5-hour, session, weekly reset, usage bars, capacity text | Chat nuevo más pequeño, espera, extra usage si aplica |
| Claude Code subscription auth | Plan/session window shared with Claude surfaces | Ejecuta /usage o lee el reset message | session limit, weekly limit, model limit | Espera reset, baja model/workload o usa extra usage |
| Claude Code API key | Console workspace or cloud project | Ejecuta /status y confirma credential | API-key route, provider logs, 429 body | Baja concurrency o revisa owner dashboard |
| Direct Anthropic API | Anthropic workspace/model rate limit | Espera retry-after y reduce el request | HTTP 429, rate_limit_error, rate-limit headers | Reintenta una petición pequeña en la misma ruta |
| Bedrock, Vertex AI, gateway | Provider project, region, tenant, proxy policy | Revisa provider/gateway logs | Provider 429, throttling, tenant policy | Ajusta esa quota o contacta ese operator |
| Capacity, burst, acceleration | Service load or traffic shape | Espera, mira status, ralentiza el ramp | Capacity text, recent incident, RPS spike | Retry later o verifica request pequeño misma ruta |
Regla de parada: no cambies key, plan, provider ni model antes de probar el propietario. Si el error desaparece al cambiar la ruta, quizá solo perdiste la evidencia original.
Primero identifica la ruta que produjo el limite
La frase rate limit reached no prueba por si sola que se agoto un unico bucket de Anthropic API. Una llamada directa a api.anthropic.com se verifica con HTTP 429, cuerpo de respuesta y headers. Claude Code puede usar ANTHROPIC_API_KEY y entonces el dueno es el workspace del key; una sesion de suscripcion tiene otra ventana. Bedrock, Vertex AI y un gateway pueden devolver texto parecido aunque el limite viva en el proyecto, region, tenant policy o upstream.
Haz tres preguntas: que credencial proceso la llamada, que dashboard gobierna esa credencial y si puedes reproducir una vez en la misma ruta sin cambiar modelo, provider, prompt ni region.
Si la linea realmente es Claude Code 500, 529 o una ventana de plan, usa Claude Code 500/529/rate limit router. Para el caso especifico de Claude Code rate limit, ve a Claude Code rate limit.
Claude.ai o Desktop: revisa primero la ventana de uso
Si el error aparece en Claude.ai, Desktop o mobile sin HTTP headers, tratalo primero como un limite de product surface. Usage limits controlan cuanto puedes usar Claude en un periodo; length limits controlan cuanto puede crecer una conversacion. Chats largos, archivos, tools, Research, connectors y modelos mas pesados consumen la ventana mas rapido.
No empieces con un arreglo de API key. Revisa Settings > Usage, lee el reset time, abre un chat nuevo mas pequeno si el hilo actual es grande, quita files/tools innecesarios o espera. Capacity constraints pueden ser load management temporal y no siempre aparecen como outage en status page.
Anthropic API directo: confia en los headers
En Anthropic API directo, HTTP 429 corresponde a rate_limit_error. La evidencia util es retry-after, la familia anthropic-ratelimit, RPM, input tokens per minute y output tokens per minute. Puede quedar presupuesto mensual y aun asi agotarse una ventana corta.
El siguiente request debe ser mas pequeno y lento: reduce concurrencia, baja max output, divide jobs largos, usa cache para contexto estable y reintenta una sola vez en la misma ruta.
Claude Code: revisa active route antes de cambiar planes
En Claude Code, /status y la ruta de credenciales importan. Si ANTHROPIC_API_KEY esta activo, el fallo puede pertenecer al workspace del API key, no a Pro o Max. Consulta API key vs subscription billing y Claude Code API configuration.
Por que hay usage disponible y aun asi falla
Los rate limits suelen ser rolling buckets. Un contexto largo presiona input tokens, una respuesta larga presiona output tokens, muchos requests pequenos presionan RPM y una subida brusca puede activar acceleration control.
Arregla el siguiente request sin crear ruido
Cambia una variable por vez. Agrega backoff con jitter, limita workers, baja max output, usa una cola y registra request_id, propietario de ruta, model, workspace, region, retry-after y reset headers. Verifica en la misma ruta, credencial y modelo.
Si el equipo cambia prompt, modelo, gateway y numero de workers al mismo tiempo, pierde la senal. Congela la ruta fallida y compara tres eventos: el ultimo request correcto, el primer rechazo y el rechazo actual. Busca que cambio: request rate, input tokens, output tokens, region, project, tenant, model o credencial. Ese registro convierte una sospecha general en una prueba operable.
En produccion conviene dejar dos limites propios antes del siguiente incidente: un maximo de workers por ruta y un presupuesto de output tokens por tarea. El primero protege RPM; el segundo reduce presion sobre OTPM. Cuando esos valores quedan junto al request_id, el equipo sabe si debe esperar la ventana, cambiar la forma del request o pedir mas capacidad al propietario correcto.
Limites de provider o gateway
Con Bedrock, Vertex AI o gateway, Anthropic Console puede no ser el dueno. Revisa provider quota, project/location limits, gateway logs y tenant policy antes de abrir un caso con Anthropic.
Paquete de escalacion
Escala despues de una reproduccion en la misma ruta. Incluye exact message, timestamp, request_id, headers, model, workspace/project/region, propietario de ruta, resultado de status y request minimo. No envies keys, tokens ni datos personales.
Para API directo, request_id y headers son la prueba central. Para Bedrock o Vertex AI, importan project, region y quota page. Para gateway, importan tenant, upstream route y policy hit. Si envias el paquete al propietario correcto, evitas una ronda completa de soporte que solo te devuelve al otro proveedor.
Preguntas frecuentes
Siempre es un 429 directo de Anthropic API?
No. Primero prueba el propietario de la ruta.
Debo rotar el API key?
No como primer paso. Puede ocultar la evidencia original.
Por que queda usage disponible?
Porque monthly usage y rolling RPM/token/burst windows no son lo mismo.
Que hago si Claude Status esta verde?
Sigue con la evidencia de la ruta: headers, /status, provider dashboard o gateway logs.
Cuando contacto support?
Cuando una reproduccion en la misma ruta vuelve a fallar y el paquete de evidencia esta listo.