Si Claude Code muestra 500, 529 o un mensaje de limite, no empieces con mas retry ni con un cambio de plan. Son ramas distintas: 500 empieza por status, el 529 repetido empieza por sobrecarga, y 429 o una ventana de uso clara empieza por revisar limites.
La trampa principal es el 529. Claude Code lo documenta como sobrecarga, no como tu limite personal de uso, y no como algo que debas intentar comprar para salir del problema. Primero lee la linea exacta de terminal.
| Linea exacta | Tratalo como | Primer movimiento | Verificacion en la misma ruta | Pasa a detalle cuando |
|---|---|---|---|---|
500 | error interno del servicio | Revisa Claude Status, espera poco y repite el mismo comando una vez | Mismo comando, ruta de autenticacion y modelo | Persiste con status verde o sin incident |
529 repetido | sobrecarga de capacidad | Revisa status, espera; cambia /model solo si la tarea lo permite | Misma session y ruta tras un cool-down | Se repite despues de revisar status y ruta |
429 | limite de API key o provider | Revisa ventana de espera, Console limits, model limits y active API path | Retry solo tras la ventana o path correction | Headers o Console aun muestran limits agotados |
Server is temporarily limiting requests, session limit, weekly limit | throttle o usage window de Claude Code | Cool down o revisar plan/session window | Retomar el mismo workflow tras cambiar la ventana | El mensaje nombra plan o reset window |
| El plan no coincide con tus limites | route override | Ejecuta /status y mira ANTHROPIC_API_KEY o proxy | Confirma subscription o API-key route prevista | La misma route falla con una rama limpia |
Primero la rama, no la teoria
La referencia de errores de Claude Code conecta runtime errors con codigos de Claude API. Tambien indica que Claude Code reintenta fallos transitorios antes de mostrar muchos mensajes. Cuando ves la linea, ya no estas al comienzo del incidente: estas en el punto donde toca elegir rama.
La pregunta util no es "Claude esta caido?" ni "se me acabo la cuota?". La pregunta util es a que clase documentada pertenece esa linea. 500 pide status, espera breve y un retry en la misma ruta. 529 repetido pide tratar capacidad como owner. 429 real pide revisar API key o provider limits. Un session o weekly limit pide mirar la ventana de uso. Una ruta rara pide /status antes de sacar conclusiones de plan.
La frontera de status debe ir con fecha. En la comprobacion del 20 de abril de 2026, Claude Status mostraba Claude API y Claude Code como operational, aunque el historial tambien tenia incidents resueltos ese mismo dia y el 15 de abril. Eso no demuestra que tu fallo actual sea local; solo explica por que el flujo empieza con status y sigue con same-path verification.
Rama 500: status, espera breve, un retry
Los Anthropic API docs asignan HTTP 500 a api_error. La referencia de Claude Code muestra API Error: 500 Internal server error como un problema del lado de infraestructura, no como una consecuencia directa de tu prompt, settings o cuenta.
La secuencia segura es pequena:
- Revisa Claude Status.
- Espera poco y repite el mismo command o message una vez.
- Mantén el mismo model y auth route durante la verificacion.
- Si no hay incident publicado y la misma ruta falla, conserva detalles y usa
/feedbacko support route.
Si tu sintoma exacto es API Error: 500 persistente, sigue con la guia de Claude Code API Error 500. Esta rama solo evita tratar 500 como limite o como 529.
Rama 529: sobrecarga, no tu limite de uso
Claude Code es directo con 529 repetido: la API esta temporalmente al limite de capacidad entre usuarios, Claude Code ya reintento antes de mostrarlo, y 529 no es tu usage limit ni cuenta contra quota.
El primer movimiento no es upgrade.
- Revisa si status muestra capacity notices.
- Espera unos minutos.
- Usa
/modelsolo si la tarea puede aceptar otro model. - Verifica la misma session y route despues del cool-down.
Si 529 sigue volviendo tras esas comprobaciones, pasa a la guia de Claude Code overloaded error. No llames rate limit al 529: 529 overloaded_error y 429 rate_limit_error llevan a acciones distintas.
Ramas de limite: 429, temporary limiting, ventanas de plan
"Limite" puede significar al menos tres cosas dentro de Claude Code.
La primera es API 429 rate_limit_error real. Esta rama pertenece a API key, provider project, model-specific limits, concurrency y retry-after. Para ella, usa la guia de Claude Code rate limit.
La segunda es el mensaje Server is temporarily limiting requests (not your usage limit). Tratalo como un throttle corto: espera, revisa status si se repite y vuelve a probar la misma route. No prueba que tu plan este agotado.
La tercera es una ventana de uso real: session limit, weekly limit, Opus limit o reset time. Esa rama pertenece a /usage, reset timing y plan window. Para continuar, usa rate-limit reached o usage limits diagnosis.
Rama route override: revisa auth antes de culpar al plan
La ayuda de Claude Code sobre API key environment variables dice que ANTHROPIC_API_KEY tiene prioridad sobre una authenticated subscription, y que /status puede mostrar el auth method activo. Por eso la verificacion de route forma parte de la recuperacion.
Haz una comprobacion sin exponer secretos:
- Ejecuta
/statusdentro de Claude Code. - Comprueba si
ANTHROPIC_API_KEYesta configurado, sin pegar la key en ningun sitio. - Confirma si usas subscription auth, direct Anthropic API, Bedrock, Vertex o proxy.
- Repite la misma request en la route que querias usar.
Si corregir la route cambia el resultado, el problema real era route mismatch. Si la intended route sigue fallando con la misma rama, ya tienes evidencia mas limpia.
Guarda evidencia antes de escalar
Los errores de Anthropic API pueden incluir request_id, y las respuestas pueden incluir header request-id. Claude Code tambien ofrece /status, /model, /usage y /feedback.
Guarda un paquete corto:
- linea exacta de terminal con
500,529,429o el mensaje completo de limite; - hora y timezone;
- resultado de Claude Status en ese momento;
- active route desde
/status; - model usado y si cambiaste
/model; - resultado del same-path retry;
- request ID o feedback context, si existe.
Cuando ya clasificaste la rama, hiciste la accion minima y la misma ruta sigue fallando, deja de improvisar. Mas retry al azar destruye la evidencia.
Preguntas frecuentes
Claude Code 529 es un rate limit?
No. Claude Code documenta 529 repetido como overload. El rate limiting real de API es 429 rate_limit_error; temporary limiting y plan-window messages son ramas aparte.
Que hago primero con Claude Code API Error 500?
Revisa Claude Status, espera poco y repite el mismo command o message una vez. Si no hay incident y la misma ruta falla, guarda detalles y pasa a la guia de 500 o a /feedback.
Y si Claude Status esta verde pero Claude Code falla?
Un status verde solo descarta la rama de live incident publicado. Aun debes comprobar error exacto, active auth route, model y same-path retry.
Como se si una API key esta sobrescribiendo mi subscription?
Ejecuta /status en Claude Code y comprueba si ANTHROPIC_API_KEY esta definida en tu shell o environment. No pegues la key.
Debo mejorar el plan cuando veo 529?
No como primer movimiento. Un 529 repetido es una rama de overload. Upgrade solo encaja con mensajes explicitos de plan-limit o usage-window.