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

Diseñar reintentos que no agraven la incidencia

Trata el 529 como un «429 sin Retry-After». Usa retroceso exponencial desde unos 2 segundos, añade jitter, fija un límite de 30–60 segundos y, después de unas cinco veces, abandona y pon el trabajo en cola. La clave es el jitter. Sin él, todos los clientes vuelven en el mismo instante y prolongan la sobrecarga de la que intentaban salir.

No lo descartes: pásalo a otra ruta

Define una cadena de respaldos para las rutas sensibles a la latencia. Si el endpoint es compatible con OpenAI, solo tienes que cambiar una cadena; no necesitas crear otro SDK ni 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

Sospechar de tu propio código es el último recurso

Si solo un tipo concreto de solicitud devuelve 529 y otras llamadas del mismo momento pasan, no es una incidencia general. Comprueba si esa ruta envía un prompt anormalmente grande o realiza llamadas consecutivas dentro de un bucle estrecho. Si, por el contrario, todas las llamadas devuelven 529 a la vez y luego se recuperan por sí solas, la causa es la capacidad. En ese caso debes ajustar los reintentos y el respaldo, no refactorizar.

¿Es culpa mía el 529?

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

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

El 429 significa que superaste el límite y el servidor funciona con normalidad. El 529 significa que el propio servidor está sobrecargado y tu límite es normal. Ambos deben reintentarse, pero solo el 429 incluye la indicación Retry-After.

¿Cuánto suele durar el estado 529?

No se puede predecir ni garantizar. Por eso la respuesta correcta es retroceso con límite superior y cola, no insertar en el código un tiempo de espera fijo. Si la ruta tiene una tolerancia de latencia, el respaldo debe hacerse cargo en lugar de esperar.

¿También se cobran las llamadas que fallan con 529?

A través de Kunavo, no. Las solicitudes que terminan con error no se facturan. Si tienes un contrato directo, se aplican las reglas de facturación del proveedor correspondiente.