Si una petición a Claude API devuelve 529 overloaded_error, la primera hipótesis operativa debe ser sobrecarga del lado de Anthropic. No es una prueba inmediata de que tu key, billing, cuota o account estén rotos. La trampa cercana es tratarlo como 429 rate_limit_error: 429 pertenece a la rama de rate limit o cuota, mientras que 529 pertenece a capacidad.
El primer minuto debe ser pequeño y ordenado. Registra el resultado de Claude Status con hora, ejecuta un retry corto con jitter y límite, reduce la presión si controlas el caller, y verifica la misma ruta: mismo modelo, endpoint, auth path y request shape. Si esa misma ruta sigue devolviendo 529, guarda el error body y el request_id, y escala con evidencia.
El estado público solo es una señal con timestamp. Durante este run, a 2026-04-29 11:02 UTC, la API pública de estado reportaba all systems operational, pero el feed de incidentes aún mostraba eventos de elevated errors ya resueltos el 28 y 29 de abril UTC. Un estado verde reduce la rama probable, pero no demuestra que tu ruta exacta ya se recuperó.
Tabla de decisión en 60 segundos
Lee la señal exacta antes de tocar keys, billing, modelo, prompt o provider.
| Señal exacta | Trátalo como | Primer movimiento | Verificación de la misma ruta | Detén o escala cuando |
|---|---|---|---|---|
529 u overloaded_error | Sobrecarga de Anthropic | Verifica live status y usa capped retry con jitter | Mismo modelo, endpoint, auth route y request shape | Persiste tras estado, retry budget y reducción de presión |
429 o rate_limit_error | Límite o cuota | Revisa retry-after, limits y credential route | Reintenta solo tras ventana permitida o route correction | Headers y Console siguen apuntando a límite agotado |
500 o api_error | Error de servidor | Verifica status, conserva request evidence, retry breve | Misma petición tras una pausa corta | No hay incidente y la misma ruta falla repetidamente |
504 o timeout_error | Timeout | Reduce duración, usa stream o divide el trabajo | Misma tarea tras un cambio intencional de forma | La petición larga sigue expirando |
| Claude Code muestra 529 repetido | Superficie Claude Code | Aclara el sentido API y pasa a la rama terminal | Misma sesión y route tras cooldown | Persiste tras status y route check |
La regla práctica es directa: 529 es overload first. No empieces con rotación de key, subida de plan o reescritura aleatoria de prompt salvo que la respuesta exacta cambie a una rama que justifique esos movimientos.
Qué significa 529 en Claude API
La documentación de errores de Anthropic define HTTP 529 como overloaded_error. En la misma tabla separa 429 rate_limit_error, 500 api_error y 504 timeout_error. Esa separación oficial debe ser el límite de recuperación.
La diferencia importante es ownership. Un 529 real dice que el servicio está sobrecargado o en presión de capacidad. Tu código aún debe comportarse mejor durante esa condición, pero la primera interpretación no es “mi account se quedó sin quota”. Un 429 real apunta a request rate, acceleration limits, model limits o techos de account/provider. Un 500 exige server-error handling y evidencia. Un 504 exige mirar duración, streaming y forma de petición.
Los malos arreglos nacen cuando todos los blocked requests se vuelven una sola categoría. El equipo ve un fallo y aplica la receta familiar: bajar velocidad como si fuera 429, cambiar key como si fuera auth, o cambiar provider como si la route failure ya estuviera probada. Esos pasos sirven en otras ramas, no como primer movimiento de un 529 limpio.
Conserva request_id desde el principio. Anthropic indica que las respuestas de error incluyen request_id, y los headers pueden exponer request-id. Cuando 529 persiste, ese identificador vale más que una narración larga sobre experimentos locales.
Bucle de recuperación seguro
Un handler de 529 en producción debe ser aburrido: confirmar estado, retry breve, reducir presión, verificar la misma ruta y después detener o escalar. La meta no es hacer que el cliente “intente más fuerte”. La meta es no empeorar una sobrecarga y conservar evidencia suficiente.
Empieza con live status. Registra el resultado y la hora en UTC o en tu zona operativa. Si hay un active incident, no cambies a la vez modelo, endpoint, auth y tamaño de petición. Mantén la forma del failing request, pausa y vuelve a probar cuando la degradación mejore.
Si el estado está verde o no hay incidente publicado, usa un bounded retry budget. Una implementación razonable incluye exponential backoff, jitter, límite de intentos o límite de tiempo total. Solo reintenta trabajo seguro de repetir. Lecturas y generation attempts con deduplicación caller-side son más fáciles que workflows con efectos secundarios.
Después reduce caller pressure. Baja concurrency, pausa non-urgent batch jobs, aplica queue backpressure o pasa una función secundaria a degraded mode. No significa que 529 sea culpa tuya. Significa que cada cliente que reintenta agresivamente durante provider overload añade presión al mismo sistema limitado.
Por último verifica la misma ruta. Mantén estables model, route, auth owner, endpoint, region/proxy path y request shape, salvo que un cambio sea el paso intencional de recuperación. Si cambias cinco variables y el siguiente call funciona, ya no sabes si la sobrecarga se despejó, si cambiaste route o si la petición se volvió más ligera.
Controles de producción para 529 repetido
El procedimiento manual es la versión humana. Tu servicio debe automatizar la misma disciplina. Usa retry budget, no retries infinitos. Limita attempts, elapsed time y el momento en que la respuesta ya no tiene valor para el caller. Un chat turn, un background batch y un transactional workflow no deberían compartir política.
Añade jitter. Los intervalos fijos sincronizan tráfico, justo lo que una API sobrecargada no necesita. Jitter reparte solicitudes y hace que la recuperación sea menos puntiaguda.
Instala un circuit breaker alrededor de 529 repetidos. Si la tasa supera tu threshold, abre el breaker, encola trabajo no urgente, degrada optional features y muestra un mensaje claro al usuario sin prometer recuperación inmediata. Cierra el breaker solo después de un pequeño same-path probe.
Separa “reducir presión” de “cambiar ruta”. Reducir presión significa menos concurrency, batch windows más pequeños o jobs diferidos. Cambiar ruta significa otro modelo, endpoint, provider o auth owner. Route change puede ser una decisión de negocio, pero cambia tu evidence trail y a veces el comportamiento del producto.
La observabilidad puede ser simple: error type, HTTP status, model, endpoint, auth route, request size class, retry count, final outcome y request_id. Esos campos bastan para responder lo importante durante un pico 529: ¿la misma ruta se recuperó dentro del budget, o sigue siendo provider overload?
Cuando 529 aparece en Claude Code
Empieza con el significado API de 529 overloaded_error. Si el síntoma está dentro de Claude Code, la superficie terminal añade reglas propias, pero no convierte 529 en billing issue.
La documentación de Claude Code describe el 529 repetido como temporary capacity across users, dice que Claude Code ya reintentó antes de mostrar el mensaje y lo separa de usage-limit o quota wording. Por eso el caso terminal pertenece a la guía de Claude Code overloaded error, no a una página genérica de billing.
Si la línea terminal mezcla 500, 529, 429, temporary limiting o route confusion, usa el router más amplio de Claude Code 500 vs 529 vs rate limit. Esa ruta existe porque el terminal puede comprimir varias ramas en un solo momento de estrés.
Los equipos API también deben revisar route ownership. Una variable de entorno, proxy o provider wrapper puede hacer que la petición pase por un camino que no pretendías probar. Si 529 aparece solo en un wrapper path, compara la misma petición en la ruta esperada antes de concluir que toda la superficie Claude API falla.
Paquete de evidencia para escalar
La escalada empieza después de completar el recovery path ordenado. Eso significa que el estado actual está registrado, el retry fue bounded, la presión se redujo donde era posible y la misma ruta todavía devuelve 529.
Envía un paquete compacto:
- HTTP status y error type exactos, incluyendo
529 overloaded_error - error body completo con
request_idcuando exista - model, endpoint, SDK o gateway route, y auth owner
- resultado de Claude Status con timestamp y cualquier incident note reciente relevante
- retry count, backoff window y si se usó jitter
- concurrency o batch pressure al momento del fallo
- minimal reproduction request shape, sin secretos
- impacto de negocio en una frase, como blocked production job, degraded user flow o non-urgent batch delay
La brevedad es deliberada. Support no necesita todos tus experimentos locales. Necesita prueba de que la rama es 529, de que el client no creó un retry storm y de que la misma ruta siguió fallando tras controles razonables.
Preguntas frecuentes
¿Claude API 529 es lo mismo que 429?
No. Anthropic define 529 como overloaded_error y 429 como rate_limit_error. Un 529 verdadero es overload first. Un 429 verdadero pertenece a rate limit.
¿Un 529 significa que mi account o billing están rotos?
No como primera interpretación. Un 529 overloaded_error limpio apunta a capacity overload. Billing, key o quota importan cuando cambia el error exacto, la route no es la esperada o aparece otra señal.
¿Qué hago si Claude Status está verde pero sigo recibiendo 529?
Trata el verde como timestamped signal, no como prueba de recuperación de tu ruta exacta. Ejecuta un same-path retry corto con jitter, reduce presión y escala con request_id si el mismo model, route, auth path y request shape siguen fallando.
¿Cuántos retries son seguros?
Usa un budget, no un número universal. Limita attempts o elapsed time, añade jitter y reintenta solo trabajo seguro de repetir. Si el valor visible para el usuario expira rápido, el budget debe ser corto.
¿Debo cambiar modelo o provider cuando aparece 529?
Solo como route decision explícita. Si el workload tolera otro modelo o route, cambiar puede mantener vivo un flujo no crítico. Pero como primer diagnóstico oculta si el original path se recuperó.
¿Qué debo enviar a Anthropic support?
Envía error body, request_id, model, endpoint o gateway route, auth owner, status timestamp, retry timeline, pressure level y minimal reproduction. Quita secretos y deja la rama evidente.
Regla operativa
Claude API 529 es una rama overload-first. Verifica live status con timestamp, reintenta solo con capped jittered budget, reduce caller pressure, confirma la misma ruta y escala únicamente cuando esa ruta sigue devolviendo 529 overloaded_error con evidencia limpia.