Error 529 overloaded_error de la API de Claude: qué significa y cómo sobrellevarlo

Reintentar sin agravar la incidencia

Trata 529 como un 429 sin Retry-After: aplica un backoff exponencial desde aproximadamente 2 segundos, con jitter, limitado a 30–60 segundos; abandona después de unos cinco intentos y coloca el trabajo en una cola. El jitter es crucial: sin él, todos los clientes vuelven al mismo tiempo y prolongan exactamente la sobrecarga de la que intentan salir.

Cambiar de proveedor en lugar de fallar

Para las rutas sensibles a la latencia, define una cadena de fallback. En un endpoint compatible con OpenAI, basta con cambiar una cadena de texto: no necesitas un segundo SDK ni una segunda cuenta:

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          # überlastet — nächste Stufe versuchen
    raise last

Solo después revisa tu propio código

Si el error 529 aparece solo con un tipo de solicitud y las demás llamadas funcionan al mismo tiempo, no se trata de una incidencia generalizada: comprueba si esa ruta envía prompts inusualmente grandes o se ejecuta en un bucle muy estrecho. Si, por el contrario, afecta a todas las llamadas a la vez y desaparece por sí solo, era un problema de capacidad; entonces corresponde usar reintentos y fallback, no refactorizar.

¿Un error 529 es culpa mía?

No. Es un problema de capacidad del proveedor. Tu responsabilidad se limita a no agravar la incidencia (backoff, jitter) y a tener un destino alternativo si dura más que tu presupuesto de latencia.

529 o 429: ¿cuál es la diferencia?

429 significa que has superado tus límites y el servidor está sano. 529 significa que el propio servidor está sobrecargado y tu cuota está en orden. Ambos se pueden reintentar; solo 429 incluye una indicación Retry-After.

¿Cuánto suele durar una fase 529?

No se puede predecir ni garantizar; por eso la respuesta correcta es un backoff limitado junto con una cola, no un tiempo de espera escrito en el código. Si tu ruta tiene un presupuesto de latencia, el fallback debe actuar en lugar de esperar.

¿Se cobran las llamadas 529 fallidas?

En Kunavo no: una solicitud que termina con un error no se factura. Con un contrato directo, depende de las reglas de facturación del proveedor correspondiente.