Error 529 overloaded_error de la API de Claude — significado y forma correcta de actuar

Diseñar reintentos que no agraven la incidencia

Trata el 529 como un «429 sin Retry-After». Usa retroceso exponencial desde unos 2 segundos, con jitter, un límite de 30–60 segundos y abandona después de unas 5 veces para enviar el trabajo a una cola. Lo importante es el jitter. Sin él, todos los clientes regresan al mismo tiempo y prolongan exactamente la congestión de la que intentaban salir.

No lo descartes: desvíalo

Prepara una cadena de respaldos para las rutas sensibles a la latencia. Con un endpoint compatible con OpenAI, solo cambia una cadena; no necesitas añadir SDK ni cuentas:

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 paso

Si solo ciertos tipos de solicitudes producen 529 y otras llamadas del mismo momento funcionan, no se trata de una incidencia general. Comprueba si esa ruta envía prompts anormalmente grandes o dispara llamadas en un bucle corto. En cambio, si todas las llamadas se convierten simultáneamente en 529 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 reduce a dos cosas: no amplificar la incidencia (retroceso y jitter) y preparar un destino de desvío para cuando la incidencia supere tu tolerancia de latencia.

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

El 429 significa que tú superaste el límite y el servidor funciona con normalidad. El 529 significa que el servidor está sobrecargado y tus límites y saldo son normales. Ambos pueden reintentarse, pero solo el 429 incluye la indicación Retry-After.

¿Cuánto suele durar un 529?

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

¿Se cobran las llamadas que fallan con 529?

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