Error 529 overloaded_error de la API de Claude — qué es y cómo absorberlo

Reintentar sin amplificar la incidencia

Trata el 529 como un 429 sin Retry-After: backoff exponencial desde unos 2 segundos, con jitter, con tope en 30–60 segundos, rendirse tras unos cinco intentos y encolar el trabajo. El jitter es la parte que importa: sin él todos los clientes vuelven a la vez y prolongan justo la saturación de la que intentan salir.

Conmutar en vez de caer

En las rutas sensibles a la latencia, define una cadena de reserva. En un endpoint compatible con OpenAI eso es una sola cadena de texto cambiada — sin un segundo SDK y sin una segunda cuenta:

PREFERRED = ["claude-sonnet-4-6", "claude-haiku-4-5", "gemini-2-5-flash"]

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          # saturado — probar el siguiente nivel
    raise last

Y solo entonces mirar tu código

Si los 529 aparecen únicamente en un tipo de petición mientras las demás llamadas pasan a la vez, no es una incidencia general: comprueba si esa ruta envía prompts inusualmente grandes o dispara en un bucle cerrado. Si en cambio afecta a todas las llamadas de golpe y desaparece solo, era capacidad — y entonces el trabajo pertenece al reintento y a la reserva, no a una refactorización.

¿Un 529 es culpa mía?

No. Es capacidad del lado del proveedor. Tus únicas responsabilidades son no amplificar la incidencia (backoff, jitter) y tener una salida de reserva si la incidencia dura más que tu presupuesto de latencia.

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

429 significa que cruzaste tus límites, el servidor está bien. 529 significa que el propio servidor está saturado, tu cuota está bien. Ambos son reintentables; solo 429 viene con una pista Retry-After.

¿Cuánto dura normalmente un episodio de 529?

No es predecible ni se puede garantizar — por eso la respuesta correcta es un backoff con tope más una cola, y no una espera escrita a fuego en el código. Si tu ruta tiene un presupuesto de latencia, el relevo lo toma la reserva en vez de la espera.

¿Se facturan las llamadas que acaban en 529?

A través de Kunavo no: una petición que termina en error no se factura. En contrato directo depende de las reglas de facturación del proveedor correspondiente.