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

Evita que los reintentos amplifiquen la incidencia

Trata 529 como «un 429 sin Retry-After»: retroceso exponencial desde unos 2 segundos, con jitter, un límite de 30〜60 segundos y abandono tras aproximadamente cinco intentos para enviar el trabajo a una cola. Lo que realmente funciona es el jitter: sin él, todos los clientes vuelven al mismo tiempo y prolongan intacta la congestión de la que intentaban escapar.

No caigas: rodéalo

Define de antemano una cadena de respaldo para las rutas sensibles a la latencia. En endpoints compatibles con OpenAI, basta con cambiar una cadena; no necesitas integrar otro SDK ni abrir otra 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          # 過載 —— 試下一個
    raise last

Deja para el final la sospecha sobre tu propio programa

Si solo un tipo de solicitud produce 529 mientras las demás llamadas funcionan al mismo tiempo, no se trata de una incidencia general: comprueba si esa ruta envía prompts anormalmente grandes o realiza envíos consecutivos en un bucle muy corto. En cambio, si todas las llamadas empiezan a producir 529 simultáneamente y se recuperan solas después de un tiempo, la causa es la capacidad; debes ajustar los reintentos y el respaldo, no reestructurar el código.

¿El 529 es problema mío?

No. Es un problema de capacidad del proveedor. Tu responsabilidad se limita a dos cosas: no amplificar la incidencia (retroceso y jitter) y tener una vía de escape cuando la incidencia supere tu presupuesto de latencia.

¿Cuál es la diferencia entre 529 y 429?

429 significa que superaste tu propio límite y el servidor está sano; 529 significa que el servidor está sobrecargado y tu cuota está bien. Ambos pueden reintentarse, pero solo 429 incluye una indicación Retry-After.

¿Cuánto suele durar un 529?

No se puede predecir ni garantizar; por eso la respuesta correcta es «retroceso limitado más una cola», no fijar en el código un tiempo de espera. Si esa ruta tiene un presupuesto de latencia, debe hacerse cargo un respaldo, no una espera.

¿Se cobran las llamadas que fallan con 529?

A través de Kunavo, no: las solicitudes que terminan con un error no se incluyen en la facturación. Si contratas directamente con el proveedor, depende de sus reglas de facturación.