Referencia de configuración de reintentos y tiempos de espera del SDK de Python
Esta página infiere un diseño genérico de lista de referencia: agrupa la configuración de reintentos y tiempos de espera del SDK de Python de anthropic según dónde se configuran, para que pueda buscar la opción correcta sin tener que releer toda la referencia del SDK.
Cada configuración que se muestra se aplica de manera idéntica a Anthropic() y AsyncAnthropic(), a menos que se indique lo contrario.
Cómo usar esta referencia
- Comienza con el grupo Valores predeterminados a nivel de cliente si estás estableciendo la política para toda tu aplicación.
- Usa el grupo Anulaciones por solicitud cuando una llamada específica necesite un comportamiento diferente al predeterminado del cliente.
- La tabla Qué se reintenta te indica qué fallos maneja automáticamente el SDK, para que no crees lógica de reintento redundante sobre ella.
- Vuelve a visitar esta página cada vez que agregues un nuevo punto de llamada con requisitos inusuales de latencia o confiabilidad (un bucle de agente de larga duración, una solicitud orientada al usuario con un SLA estricto, etc.).
Valores predeterminados a nivel de cliente
Establece estos valores al construir el cliente. Se aplican a cada solicitud realizada a través de esa instancia de cliente, a menos que se anulen por solicitud.
import anthropic
client = anthropic.Anthropic(
max_retries=4, # el valor predeterminado es 2
timeout=30.0, # segundos; el valor predeterminado es 600.0 (10 minutos)
)| Configuración | Tipo | Predeterminado | Qué controla |
|---|---|---|---|
max_retries | int | 2 | Cuántas veces el SDK reintenta automáticamente una solicitud después de un fallo que se puede reintentar, antes de generar una excepción. |
timeout | float o httpx.Timeout | 600.0 segundos | El límite de tiempo de reloj de pared para cada intento de solicitud individual. Se aplica por intento, no a toda la secuencia de reintentos. |
base_url | str | https://api.anthropic.com | No es una configuración de reintento/tiempo de espera, pero se configura comúnmente junto con ellas al enrutar a través de un proxy; se incluye aquí ya que se establece en el mismo punto de llamada. |
Anulaciones por solicitud
Usa with_options(...) para anular una configuración para una sola llamada sin cambiar los valores predeterminados del cliente.
# Una llamada necesita un tiempo de espera más corto y sin reintentos: una solicitud de interfaz de usuario sensible a la latencia
response = client.with_options(
max_retries=0,
timeout=5.0,
).messages.create(
model="claude-sonnet-5",
max_tokens=200,
messages=[{"role": "user", "content": "Clasificación rápida: ¿es esto spam? ..."}],
)| Forma de la llamada | Efecto |
|---|---|
client.with_options(max_retries=N) | Anula el número de reintentos para las llamadas realizadas en el objeto devuelto; el client original no se modifica. |
client.with_options(timeout=N) | Anula el tiempo de espera por intento de la misma manera. |
client.with_options(max_retries=N, timeout=N) | Ambas anulaciones se pueden combinar en una sola llamada. |
with_options(...) devuelve un nuevo objeto similar a un cliente; no modifica el client original, por lo que el patrón es seguro de usar en línea por llamada sin afectar otras rutas de código que comparten el mismo cliente.
Qué se reintenta automáticamente
| Fallo | ¿Se reintenta por defecto? | Por qué |
|---|---|---|
Error de red/conexión (APIConnectionError) | Sí | Transitorio: es posible que la solicitud ni siquiera haya llegado al servidor. |
408 Request Timeout | Sí | Transitorio: el servidor dejó de esperar; es seguro volver a intentarlo. |
409 Conflict | Sí | A menudo transitorio en el uso de la API (por ejemplo, un recurso en un estado temporal). |
429 Too Many Requests (RateLimitError) | Sí | Transitorio: retroceder y reintentar, respetando retry-after cuando esté presente. |
Errores de servidor 5xx | Sí | Transitorio: un problema en la infraestructura de Anthropic, no en tu solicitud. |
400 Bad Request | No | No se puede reintentar: la solicitud en sí está mal formada; reintentarla reproducirá el mismo error. |
401 Unauthorized | No | No se puede reintentar: una clave de API incorrecta o faltante no se corregirá sola al reintentar. |
404 Not Found | No | No se puede reintentar: típicamente un ID de modelo o punto final no válido. |
Comportamiento de retroceso (Backoff)
- Los reintentos utilizan un retraso creciente entre intentos (retroceso exponencial con jitter), no un intervalo fijo.
- La cabecera
retry-afterde una respuesta429, cuando está presente, se respeta como un retraso mínimo antes del siguiente intento. - El SDK no expone un control detallado sobre la curva de retroceso en sí (retraso base, multiplicador);
max_retrieses la palanca principal que controlas.
Granularidad del tiempo de espera
| Preocupación | Comportamiento |
|---|---|
Qué limita timeout | Cada intento HTTP individual, no el tiempo total en todas las reintentos. |
| Tiempo de reloj de pared en el peor de los casos | Puede alcanzar aproximadamente timeout × (max_retries + 1) si cada intento excede el tiempo de espera y se reintenta. |
| Solicitudes de streaming | timeout todavía se aplica a establecer la conexión y recibir los primeros bytes; un stream lento pero que progresa no se interrumpe por el mismo reloj. |
| Pasar un número simple | Se trata como segundos tanto para Anthropic() como para AsyncAnthropic(): el SDK de Python no usa milisegundos. |
Elección de valores para escenarios comunes
| Escenario | max_retries sugerido | timeout sugerido | Razonamiento |
|---|---|---|---|
| Solicitud interactiva, orientada al usuario | 1-2 | 10-30 segundos | Los usuarios notan el retraso; falla rápido y muestra un error en lugar de reintentar durante mucho tiempo. |
| Trabajo de procesamiento por lotes o ETL en segundo plano | 4-6 | 60+ segundos | Nadie está esperando de forma síncrona; favorece el éxito eventual sobre la velocidad. |
Bucle de agente largo con max_tokens grande | Predeterminado del cliente (2), combinado con streaming | 600 segundos (predeterminado del cliente) suele ser suficiente una vez que el streaming evita el riesgo de tiempo de espera de una sola llamada grande no streaming | El streaming (ver Relacionados) es la solución principal para los tiempos de espera de salida grandes, no solo un valor de timeout más alto. |
| Llamada de verificación de estado o prueba de humo | 0 | 5-10 segundos | Quieres saber inmediatamente si algo está mal, no después de varios reintentos. |
Preguntas frecuentes
¿Cuál es el valor predeterminado de max_retries si no lo establezco?
2.
El SDK reintenta una falla transitoria hasta dos veces más (tres intentos en total) antes de generar una excepción.
¿Cuál es el tiempo de espera predeterminado si no lo establezco?
600.0 segundos (10 minutos), aplicado por intento.
¿Cambia with_options() el cliente original?
No.
client.with_options(...) devuelve un nuevo objeto con las anulaciones aplicadas; el client original y sus valores predeterminados no se modifican.
¿El tiempo de espera se aplica a toda la secuencia de reintentos o solo a un intento?
Solo a un intento.
Si cada intento excede el tiempo de espera y se reintenta, el tiempo de reloj de pared en el peor de los casos puede alcanzar aproximadamente timeout × (max_retries + 1).
¿Reintentará el SDK una solicitud de 400 Bad Request?
No.
Los códigos 400, 401, 403 y 404 se tratan como no reintentables, ya que la solicitud en sí (no la red o el servidor) es el problema, y reintentarla sin cambios fallaría de nuevo.
¿La configuración de reintentos/tiempos de espera es diferente entre Anthropic() y AsyncAnthropic()?
No.
Ambas clases de cliente aceptan los mismos argumentos de constructor max_retries y timeout y admiten el mismo patrón with_options(...).
¿Una respuesta 429 respeta la cabecera retry-after de la API?
Sí.
Cuando la respuesta incluye una cabecera retry-after, el SDK la respeta como un retraso mínimo antes del siguiente intento de reintento.
¿Debo establecer max_retries en 0 para una verificación de estado?
Es una opción razonable.
Una verificación de estado generalmente quiere saber inmediatamente si la API es accesible, en lugar de enmascarar una interrupción real detrás de varios intentos de reintento.
¿Puedo establecer un tiempo de espera diferente para llamadas de streaming y no streaming?
Sí, usando el mismo patrón with_options(timeout=...) por llamada, o estableciendo diferentes tiempos de espera en instancias de cliente separadas si la división es consistente en toda tu aplicación.
¿Aumentar max_retries soluciona una respuesta lenta que finalmente tiene éxito?
No directamente.
max_retries aborda los fallos, no la lentitud; una solicitud que tiene éxito pero es simplemente lenta es una preocupación de timeout, y para salidas grandes, cambiar a streaming suele ser la mejor solución.
¿Qué excepción atrapo si se agotan los reintentos?
La excepción tipificada que coincide con el fallo subyacente; por ejemplo, anthropic.RateLimitError para reintentos de 429 agotados, o anthropic.APIConnectionError para reintentos de error de red agotados. Consulta la página de referencia de excepciones para ver el mapeo completo.
Relacionados
- El modelo mental del SDK de Python de Anthropic - cómo encajan los reintentos y los tiempos de espera en el diseño del cliente
- Conceptos básicos del SDK de Python - construcción de un cliente con
max_retriesytimeout - Respuestas de streaming con el SDK de Python - evitar tiempos de espera en solicitudes con
max_tokensgrandes - Tipos de excepciones del SDK de Python de un vistazo - qué atrapar cuando se agotan los reintentos
Versiones de la pila: Escrito contra la línea de modelos Claude actual a partir de ~junio de 2026 - Claude Fable 5, Claude Opus 4.8, Claude Sonnet 5 (el predeterminado) y Claude Haiku 4.5 - y el SDK oficial de Python
anthropic(última versión 0.x). Los nombres de los modelos, las versiones del SDK y los precios cambian rápidamente; verifica los detalles actuales en platform.claude.com/docs antes de confiar en ellos.