Claude Code 529 Overloaded: causas, configuración de reintentos y soluciones

Wokey Team · 2026-09-24

Respuesta corta: un 529 significa que el modelo upstream no tiene capacidad en este momento ("overloaded"). No tiene nada que ver con tu saldo, tu cuota ni tu clave de API. Claude Code ya reintentó varias veces antes de mostrar el error. La solución más rápida es cambiar de modelo con /model, porque la capacidad se mide por modelo. Si no tienes prisa, espera unos minutos y vuelve a enviar.

El error exacto

En Claude Code ves:

API Error: Repeated 529 Overloaded errors. The API is at capacity — this is usually temporary. Try again in a moment. If it persists, check https://status.claude.com.

La documentación de Claude Code señala tres cosas al respecto:

• Es un problema temporal de capacidad que afecta a todos los usuarios.
• Claude Code ya reintentó varias veces antes de mostrarlo.
• Un 529 no es tu límite de uso y no se descuenta de tu cuota.

Cuando te conectas a través de un gateway con ANTHROPIC_BASE_URL, la última oración menciona el host del gateway en lugar de status.claude.com.

De dónde viene un 529 en Wokey

Wokey nunca genera un 529 por sí mismo; el estado siempre viene del modelo upstream. Wokey lo maneja en tres pasos:

1. Cuando el upstream informa sobrecarga (por ejemplo, el overloaded_error de Anthropic), Wokey primero reintenta tu solicitud por otra ruta upstream para el mismo modelo. No ves este paso.

2. Solo si el reintento también está sobrecargado, Wokey transmite el estado del upstream. El estado HTTP sigue siendo 529. El cuerpo usa el formato de error estándar de Wokey, con el texto propio del upstream en message:

   {"error":{"code":"upstream_overloaded","message":"Overloaded","type":"invalid_request_error"}}
   

3. Si la sobrecarga ocurre después de que la respuesta empezó a transmitirse, llega como un evento error dentro del stream en lugar de un HTTP 529.

Así que un 529 a través de Wokey significa que varias rutas upstream del mismo modelo estaban sobrecargadas a la vez, normalmente durante un pico del lado del proveedor. Estas respuestas no incluyen el encabezado Retry-After; tu cliente reintenta según su propio esquema de backoff.

Cómo distinguirlo de otros errores

Solo 529 y 503 significan "el upstream está ocupado". Los demás requieren que hagas algo.

Qué hacer

1. Espera y vuelve a enviar. La sobrecarga suele desaparecer en minutos, y los reintentos automáticos de Claude Code ya cubren los picos breves.

2. Cambia de modelo con /model. La capacidad se mide por modelo, así que cuando Opus está sobrecargado, Sonnet a menudo sigue funcionando. Ejecuta /model en la sesión y elige otro modelo; no hace falta reiniciar.

3. Para trabajos largos sin supervisión, reintenta con más insistencia. Agrega esto al bloque env de ~/.claude/settings.json:

{
  "env": {
    "CLAUDE_CODE_RETRY_WATCHDOG": "1"
  }
}

• CLAUDE_CODE_RETRY_WATCHDOG=1 hace que Claude Code reintente los errores 429 y 529 indefinidamente, con esperas de hasta 5 minutos entre intentos. Es adecuado para trabajos que dejas corriendo toda la noche.
• Si solo quieres unos pocos intentos más, configura CLAUDE_CODE_MAX_RETRIES en su lugar. Su valor predeterminado es 10 y el máximo es 15.

4. En tu propio código, deja margen para reintentar los 529. Los SDK oficiales de Anthropic reintentan los errores 5xx, 529 incluido, dos veces por defecto. Para trabajos por lotes, aumenta max_retries y agrega backoff exponencial alrededor de la llamada.

Ver un 529 en Codex

Codex trata los errores 5xx, 529 incluido, como reintentables:

• La capa HTTP reintenta 4 veces por defecto (el request_max_retries del proveedor).
• Después, la capa de stream reintenta hasta 5 veces más (stream_max_retries).
• Si todo eso falla, el error empieza con unexpected status 529, seguido del cuerpo de la respuesta.

Un code igual a upstream_overloaded en ese cuerpo indica la sobrecarga del upstream descrita arriba. La solución es la misma: espera, o cambia de modelo en config.toml. Para la configuración completa de Codex, consulta la guía de config.toml de Codex.