El 529 es el único error de Claude que no ha causado tu código: Anthropic está sobrecargada. No puedes corregirlo, pero sí absorberlo correctamente. Eso significa hacer retry con paciencia, tener un modelo de reserva y no amplificar nunca el incidente con intentos inmediatos.
El error
{
"type": "error",
"error": { "type": "overloaded_error",
"message": "Overloaded" }
}Causas y soluciones de un vistazo
| Causa | Solución |
|---|---|
| Saturación del proveedor (días de lanzamiento, incidentes regionales) | Backoff exponencial con jitter. Consulta la página de estado del proveedor en lugar de volver a desplegar. |
| Tu pico de tráfico cayó durante un incidente parcial | Distribuye los trabajos por lotes; esperar diez minutos suele resolverlo. |
| Retry inmediato en bucle | Reintentar de inmediato multiplica la carga y prolonga el incidente para todos, incluido tú. |
Haz retry como un buen ciudadano
Trata el 529 como un 429 sin encabezado retry-after: backoff exponencial comenzando en ~2 s, con jitter, un límite de 30–60 s, abandonando después de ~5 intentos y poniendo el trabajo en cola. La misma rama de código que gestiona 429 sirve para 529.
import time, random
from openai import APIStatusError
def com_retry(fn, tentativas=5):
for i in range(tentativas):
try:
return fn()
except APIStatusError as e:
if e.status_code not in (429, 500, 529):
raise
espera = min(2 ** i + random.random(), 60)
time.sleep(espera)
raise RuntimeError("esgotou as tentativas")Cambia de modelo en lugar de caer
En rutas sensibles a la latencia, define un respaldo: dentro de la misma familia (Sonnet → Haiku) el comportamiento se mantiene parecido; entre proveedores (Claude → GPT) sobrevives a un incidente completo. En un endpoint compatible con OpenAI, esto consiste en cambiar una cadena.
PREFERIDOS = ["claude-sonnet-5", "claude-haiku-4-5", "gpt-5-6-terra"]
def completar(mensagens):
ultimo = None
for modelo in PREFERIDOS:
try:
return client.chat.completions.create(
model=modelo, messages=mensagens, max_tokens=800)
except APIStatusError as e:
if e.status_code not in (429, 500, 529):
raise
ultimo = e # saturado — tenta o próximo
raise ultimoNo confundas 529 con 429 ni con 402
429 significa que superaste tus límites (el servidor está bien). 529 significa que el servidor está sobrecargado (tu cuota está bien). 402 significa saldo insuficiente. Los tres se parecen en el registro y requieren correcciones completamente distintas: solo 429 y 529 deben reintentarse.
Si llamas a través de Kunavo
En Kunavo, el mismo catálogo multimodelo está detrás de una sola clave y una sola cartera, así que el failover entre proveedores del ejemplo anterior consiste en cambiar el nombre del modelo; no requiere una segunda cuenta ni un segundo registro. Las solicitudes fallidas no se cobran. La capacidad y el precio son preguntas distintas; para la segunda, las tarifas por token están en nuestra guía de precios de la API de Claude.
Preguntas frecuentes
¿El error 529 es culpa mía?
No. Es capacidad del lado del proveedor. Tus únicas responsabilidades son no amplificar el problema (backoff con jitter) y tener adónde migrar si el incidente dura más que tu presupuesto de latencia.
¿Cuál es la diferencia entre 529 y 429?
429 significa que superaste tus límites; 529 significa que el servidor está sobrecargado. Ambos pueden reintentarse, pero solo 429 suele venir con una indicación de retry-after.
¿Me cobrarán una solicitud que devolvió 529?
No debería: la solicitud no produjo tokens. En Kunavo, las solicitudes fallidas no se descuentan del saldo.
Guías relacionadas
- Error 429 rate_limit_error en la API de Claude: qué significa y cómo resolverlo
- Error 401 authentication_error / invalid x-api-key: qué comprobar y en qué orden
- Claude API 529 overloaded_error — qué es y cómo superarlo
Encontrarás más detalles sobre el significado de los errores en referencia de errores; obtener una clave lleva un minuto mediante registro y la guía de autenticación.