Error 529 overloaded_error de la API de Claude: qué es y cómo gestionarlo

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 la parte importante: sin él, todos los clientes vuelven al mismo tiempo y prolongan exactamente la saturación de la que intentan escapar.

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, solo tienes que 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          # saturé — passer au palier suivant
    raise last

Y solo después revisa tu propio código

Si los errores 529 aparecen únicamente con un tipo de solicitud mientras 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 de repente y luego desaparece por sí solo, era un problema de capacidad; entonces corresponde usar reintentos y fallback, no rediseñar el sistema.

¿Un error 529 es culpa mía?

No. Es un problema de capacidad del proveedor. Tus únicas responsabilidades son no agravar la incidencia (backoff, jitter) y tener una salida de emergencia 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á saturado y tu cuota está en orden. Ambos se pueden reintentar; solo 429 incluye una indicación Retry-After.

¿Cuánto dura un periodo 529?

No se puede predecir ni garantizar; por eso la respuesta correcta es un backoff limitado junto con una cola, no un retraso escrito de forma fija 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?

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.