Error 529 en Claude API: configura reintentos y controla la sobrecarga

Si Claude API devuelve 529 overloaded_error, espera antes de repetir y limita cuántas solicitudes puede generar tu aplicación. La referencia oficial de errores lo define como sobrecarga temporal de la API. Un 529 confirmado no señala por sí solo una clave incorrecta ni una cuota agotada.

Para recuperar una integración, guarda el request_id, comprueba el estado del proveedor y deja que una sola capa controle los reintentos. Mientras persista la sobrecarga, reduce las solicitudes simultáneas o aplaza trabajo no urgente. La recuperación se confirma cuando una petición segura termina correctamente por la misma ruta que fallaba; si se agota el límite establecido, devuelve un resultado claro al usuario y conserva los datos para soporte.

Confirma el 529 antes de cambiar la configuración

El código HTTP y el cuerpo original del error permiten elegir la siguiente acción. Un aviso genérico de «error al enviar por sobrecarga» en una aplicación intermediaria no demuestra que Anthropic haya devuelto 529: revisa la respuesta que recibió tu servicio.

La clasificación procede de la documentación de errores de la API. En particular, un 429 por el tope mensual del nivel de uso no incluye retry-after y sigue fallando hasta que se restablece el acceso. Reintentarlo como si fuera sobrecarga transitoria no resuelve esa condición.

Anota también quién respondió. Si usas una pasarela, Amazon Bedrock u otro proveedor, su estado y sus reglas pueden intervenir. Un error generado por la pasarela no demuestra que la API directa de Anthropic haya fallado. Mantén identificados el proveedor, el endpoint y el modelo que realmente usó la solicitud.

Si el problema aparece en la terminal, la guía para reanudar Claude Code tras un 500 o 529 explica cómo recuperar la sesión y comprobar lo que ya se ejecutó. Si todavía no sabes si falló la web, Code o una integración propia, empieza por la clasificación del error interno de Claude.

Configura el SDK sin añadir reintentos ocultos

En el SDK oficial de Python, los fallos transitorios se reintentan dos veces por defecto, con retroceso exponencial. Eso permite hasta tres intentos HTTP por llamada elegible: el inicial y dos repeticiones. La referencia del SDK incluye errores de conexión, 408, 409, 429 y estados de servidor a partir de 500. Las condiciones de parada pueden reducir ese número.

Decide quién controla la política antes de añadir un bucle:

Por ejemplo, un bucle que llama al SDK tres veces, con dos reintentos internos en cada llamada, podría generar 3 × (2 + 1) = 9 intentos HTTP ante fallos elegibles, antes de contar los de una pasarela. Es un cálculo bajo esos ajustes, no una medición de tráfico. Añadir «solo tres intentos» fuera del SDK puede dar un resultado muy distinto del esperado.

Ejemplo de Python con un resultado final explícito

Este helper se integra en una aplicación que ya tiene instalado anthropic y dispone de un cliente autenticado. Recibe el cliente existente, un modelo al que tengas acceso y la lista de mensajes. No ejecuta herramientas ni implementa streaming. Delega al SDK hasta dos reintentos y no vuelve a llamar automáticamente después del error final.

from anthropic import APIConnectionError, APIStatusError, APITimeoutError


def solicitar_respuesta(client, model, messages):
    try:
        message = client.with_options(
            max_retries=2,
            timeout=20.0,
        ).messages.create(
            model=model,
            max_tokens=512,
            messages=messages,
        )
        return {
            "resultado": "completo",
            "mensaje": message,
            "request_id": message._request_id,
        }
    except APITimeoutError:
        return {"resultado": "tiempo_agotado", "request_id": None}
    except APIConnectionError:
        return {"resultado": "sin_respuesta_http", "request_id": None}
    except APIStatusError as exc:
        return {
            "resultado": "sobrecarga" if exc.status_code == 529 else "error_http",
            "status": exc.status_code,
            "request_id": exc.response.headers.get("request-id"),
        }

Cuando resultado sea completo, entrega o almacena el mensaje. Ante sobrecarga, informa de la indisponibilidad temporal y, si la tarea aún tiene valor, aplázala con su identificador de trabajo; no la vuelvas a introducir inmediatamente en otro bucle. Ante error_http, clasifica el estado antes de decidir si se repite. Un tiempo agotado o una conexión interrumpida requieren comprobar si hubo resultados o efectos posteriores antes de repetir una operación.

El ejemplo captura APIStatusError y consulta status_code para identificar 529. El código de la rama main del SDK revisado el 4 de octubre de 2026 ya lo asigna a OverloadedError, que hereda de APIStatusError, según el cliente y las excepciones. Esa lectura no confirma la versión instalada en tu servicio. Comprueba tu versión y su interfaz antes de depender de una clase más específica.

Comprobamos este helper sin conexión, con clientes y errores simulados: éxito, 529, otro estado HTTP, timeout y fallo de conexión. No es una prueba contra Claude API ni una medición de recuperación durante una incidencia.

timeout y retry-after: controla cuánto puede esperar el trabajo

timeout=20.0 no garantiza que la aplicación termine en 20 segundos. La documentación de Python establece un timeout predeterminado de diez minutos, permite modificarlo y señala que los timeouts también se reintentan dos veces por defecto. El tiempo en cola, las esperas entre intentos y los límites de otras capas no desaparecen al cambiar esa opción. Consulta los ajustes de timeout del SDK.

Distingue tres límites: cuánto puede esperar una solicitud de red, cuántos intentos se permiten y hasta cuándo sigue siendo útil el resultado para el usuario. Una respuesta de chat y un trabajo nocturno pueden usar límites diferentes. Si necesitas una hora de vencimiento total, debe controlarla tu aplicación o el proceso que supervisa el trabajo, incluyendo cola y esperas. Comprobar el reloj antes de llamar tampoco cancela una llamada que ya está en curso.

Cuando el servidor proporciona una espera, respétala. La implementación de reintentos de Python en main, revisada el 4 de octubre de 2026, prioriza retry-after-ms, después retry-after en segundos o como fecha HTTP. Acepta una espera positiva, con el límite técnico de suspensión de la plataforma; esta versión del código no aplica el antiguo corte de 60 segundos. Es una observación de esa rama, no una garantía sobre todas las versiones publicadas o pasarelas.

Si tu aplicación controla los reintentos, aplica estas decisiones:

• Con una espera válida del servidor, no vuelvas a enviar antes de que termine. Si no cabe en el tiempo restante del trabajo, detén o aplaza la tarea; recortar la espera y reintentar antes no cumple la indicación.
• Sin una espera válida, usa retroceso exponencial con variación aleatoria —jitter— y un máximo de intentos. Así evitas que todos los clientes repitan a la vez.
• Si recibes x-should-retry: false, no repitas esa respuesta. El código actual del SDK da prioridad a esa cabecera; no presupongas que siempre estará presente.
• Cuando se alcance el último intento o la tarea haya vencido, termina. No añadas una espera tras el último fallo si ya no habrá otro intento.

Estos controles deben quedar en la capa que elegiste. El helper anterior deja las esperas al SDK y limita los intentos, pero no implementa un vencimiento global ni una cola de trabajos.

Reduce la presión mientras persista la sobrecarga

Empieza por lo que puedes controlar: baja el número de solicitudes simultáneas, pausa lotes no urgentes y evita que cada usuario o proceso cree un reintento independiente. En una cola, limita tanto los trabajadores activos como el trabajo pendiente; elimina o marca como caducadas las tareas cuyo resultado ya no se necesita.

Por ejemplo, si varios trabajadores reciben 529 a la vez, permite que el servicio reduzca su concurrencia y programe las repeticiones desde una cola común. Mantén un ID por tarea de negocio para no encolarla varias veces. Cada petición HTTP puede tener un request_id distinto: ese identificador ayuda a soporte, pero no sustituye la deduplicación del trabajo.

Si los 529 se repiten en una ruta, puedes suspender temporalmente nuevas llamadas a ella mediante un cortacircuitos. Durante la pausa, conserva las tareas útiles o muestra una función temporalmente no disponible. Para volver a abrir, usa pocas solicitudes seguras y aumenta el tráfico gradualmente según sus resultados. El umbral y la duración de la pausa dependen de tu servicio; no hay un número universal que garantice disponibilidad.

Son medidas de control derivadas del carácter transitorio documentado del error y de la responsabilidad de tu aplicación. No reparan la capacidad del proveedor ni prueban que se reducirá la latencia de una petición concreta.

Comprueba que la misma ruta vuelve a funcionar

Consulta Claude Status y registra la hora y el componente relevante. Si utilizas otro proveedor, comprueba también su estado. Una página verde es una señal de ese momento; no demuestra que tu modelo, endpoint o pasarela se hayan recuperado.

Cuando corresponda volver a probar, usa una petición segura por el mismo modelo, endpoint, proveedor y forma de solicitud que fallaban. Puedes retirar datos sensibles para preparar una reproducción, pero anota cualquier cambio que afecte al tamaño o al trabajo solicitado. Una petición mínima que funciona acota el problema; no confirma por sí sola que una petición mucho mayor también funcionará.

Da por completada una llamada cuando obtengas el resultado final esperado y tu aplicación lo haya procesado. En streaming, HTTP 200 solo confirma el inicio: la referencia de errores advierte que un fallo puede llegar después. Conserva la salida ya recibida y comprueba si está completa antes de publicar un resultado o ejecutar herramientas. No concatenes ciegamente una respuesta parcial con una generación nueva ni presupongas que se reanuda desde el punto exacto del corte.

Si cambias a otro modelo o proveedor, registra el cambio como alternativa temporal. Verifica acceso, formato, herramientas y calidad aceptable para la tarea. Que la alternativa funcione permite mantener ese flujo bajo las nuevas condiciones; no demuestra que la ruta original se haya recuperado. Otra clave tampoco demuestra que exista capacidad independiente.

Cuándo parar y qué enviar a soporte

Detén las repeticiones cuando se agote el límite de intentos, venza el trabajo o la espera exigida ya no quepa en su presupuesto. Si la misma ruta sigue devolviendo 529, conserva un informe breve para Anthropic o para el proveedor que respondió:

• Fecha, hora y zona horaria; estado público observado y componente afectado.
• Código HTTP, error.type, mensaje del error e IDs de las solicitudes fallidas disponibles.
• Modelo, endpoint, proveedor, versión del SDK y pasarela, si existe.
• Número de intentos por capa, esperas aplicadas y motivo de parada.
• Solicitudes simultáneas, tamaño aproximado de la entrada y efecto de la reducción de carga.
• Una reproducción mínima sin datos sensibles y el impacto concreto: tarea aplazada, respuesta no entregada o función interrumpida.

La API incluye request_id en el cuerpo del error y request-id en la cabecera; los SDK de Python y TypeScript exponen _request_id en las respuestas correctas, según la referencia de identificadores. Una pasarela puede omitir o sustituir esos datos. Conserva los disponibles sin inventar equivalencias, y retira claves, credenciales de proxy y contenido privado antes de compartir el informe.

Preguntas frecuentes

¿Un error 529 se resuelve pagando otro plan?

No es la solución documentada para un 529 overloaded_error de la API directa. Anthropic lo define como sobrecarga temporal; los problemas de autenticación, facturación y límites tienen otros códigos. Revisa esas condiciones si la respuesta las identifica.

¿Cuántos reintentos hace el SDK de Python?

Dos por defecto para fallos transitorios elegibles, además del intento inicial. Puedes cambiar o desactivar la política con max_retries, según la documentación de Python. El número de reintentos de Claude Code corresponde a otro cliente y no debe trasladarse a tu integración.

¿Tengo que ignorar retry-after si el código es 529?

No ignores una espera válida solo por tratarse de 529. El código de Python en main revisado el 4 de octubre de 2026 la utiliza cuando es positiva. Comprueba tu versión; si la espera excede el tiempo útil del trabajo, aplaza o termina sin reintentar antes.

¿Qué hago si el estado está en verde y sigo recibiendo 529?

Mantén los reintentos limitados y comprueba la misma ruta. Si persiste tras el presupuesto establecido, devuelve un fallo o aplazamiento explícito y conserva los IDs para soporte. El estado público no sustituye el resultado de tus solicitudes.