Claude API 529 overloaded_error — qué es y cómo superarlo

El 529 es el único error de Claude que tu código no ha causado: Anthropic está sobrecargado. No puedes solucionarlo — solo absorberlo con elegancia. Eso significa reintentos pacientes, un modelo de respaldo y no agravar nunca el incidente con tormentas de reintentos instantáneos.

El error

response (HTTP 529)

{
  "type": "error",
  "error": { "type": "overloaded_error",
             "message": "Overloaded" }
}

Causas y soluciones de un vistazo

Causa	Solución
Saturación del proveedor (días de lanzamiento, incidentes regionales)	Retroceso con jitter; consulta la página de estado del proveedor en lugar de volver a desplegar tu aplicación.
Tu ráfaga llega durante un incidente leve	Distribuye los trabajos por lotes; un retraso de 10 minutos suele despejarlo.

Reintenta como un buen ciudadano

Trata el 529 como un 429 sin retry-after: retroceso exponencial a partir de aproximadamente 2 s, jitter, límite de 30–60 s, abandona después de aproximadamente 5 intentos y encola el trabajo. El fragmento de retroceso de nuestra guía de 429 gestiona el 529 en la misma rama.

Cambia de proveedor en lugar de fallar por completo

Para rutas sensibles a la latencia, define un respaldo: la misma familia (Sonnet → Haiku) mantiene el comportamiento cercano; entre proveedores (Claude → GPT) sobrevive a un incidente de todo el proveedor. En un endpoint compatible con OpenAI es un cambio de una cadena:

failover.py

PREFERRED = ["claude-sonnet-5", "claude-haiku-4-5", "gpt-5-6-terra"]

def complete(messages):
    last = None
    for model in PREFERRED:
        try:
            return client.chat.completions.create(
                model=model, messages=messages, max_tokens=800)
        except APIStatusError as e:
            if e.status_code not in (429, 500, 529):
                raise
            last = e          # saturated — try the next tier
    raise last

Si llamas a través de Kunavo

Kunavo enruta Claude a través de más de una ruta ascendente y su catálogo multimodelo convierte el cambio entre proveedores en un cambio de cadena de modelo con la misma clave y cartera — el patrón de conmutación anterior no necesita una segunda cuenta. Los 529 que te llegan nunca se facturan. La capacidad y el precio son preguntas distintas; para la segunda, las tarifas por modelo están en la lista de precios de la API de Anthropic Claude.

Preguntas frecuentes

¿Es culpa mía un 529?

No. Es capacidad del proveedor. Tus únicas responsabilidades son no agravarlo (retroceso, jitter) y tener un destino al que cambiar si el incidente supera tu presupuesto de latencia.

529 frente a 429 — ¿cuál es la diferencia?

429 significa que superaste tus límites (el servidor funciona); 529 significa que el propio servidor está sobrecargado (tu cuota funciona). Ambos permiten reintentos; solo el 429 incluye una indicación retry-after.

Guías relacionadas

Encontrarás más detalles sobre el significado de los errores en referencia de errores; obtener una clave lleva un minuto mediante registro y la guía de autenticación.