Política de reintentos
En esta página
Por qué los reintentos son esenciales
En un sistema distribuido, los errores transitorios son inevitables: tiempos de espera de red agotados, límites de tasa superados o servicios temporalmente no disponibles. Ninguno de estos fallos indica un error en tu código, pero cualquiera de ellos puede hacer que un proceso falle si nada absorbe el impacto. Una política de reintentos permite que tus actividades sobrevivan a estos errores sin intervención manual, ya que la plataforma las relanza automáticamente según la configuración que definas para cada actividad.
Configuración de una política de reintentos
El decorador @workflows.activity() acepta parámetros que gobiernan este comportamiento. Aquí tienes una actividad de llamada a API externa correctamente equipada para ser resiliente.
from datetime import timedelta
import mistralai.workflows as workflows
@workflows.activity(
start_to_close_timeout=timedelta(minutes=5),
retry_policy_max_attempts=3,
retry_policy_backoff_coefficient=2.0,
)
async def call_external_api(url: str, data: dict) -> dict:
"""Llama a una API externa con reintento automático."""
async with httpx.AsyncClient(timeout=60) as client:
response = await client.post(url, json=data)
response.raise_for_status()
return response.json()
Tres parámetros, tres funciones complementarias.
-
start_to_close_timeout— Duración máxima para un único intento de ejecución. Si la actividad no se completa en este plazo, se considera fallida y se lanza un nuevo intento. -
retry_policy_max_attempts— Número máximo de intentos. El valor por defecto depende de la plataforma. Tras este número de intentos, la actividad falla definitivamente y el flujo de trabajo recibe un error. -
retry_policy_backoff_coefficient— Multiplicador para el retraso entre intentos. Con un coeficiente de 2.0, los retrasos se duplican en cada intento (1 s, 2 s, 4 s, 8 s…). Esto se conoce como retroceso exponencial (exponential backoff).
Este mecanismo de retroceso merece atención porque su propósito no es solo esperar: da tiempo al servicio que tiene problemas para recuperarse en lugar de saturarlo. La progresión de una llamada que finalmente tiene éxito lo ilustra claramente.
Intento 1: ejecución inmediata
→ Fallo (tiempo de espera de red agotado)
→ Espera 1 segundo
Intento 2: ejecución
→ Fallo (servicio no disponible)
→ Espera 2 segundos (1 × 2.0)
Intento 3: ejecución
→ Fallo (límite de tasa)
→ Espera 4 segundos (2 × 2.0)
Intento 4: ejecución
→ ¡Éxito!
Frente a una respuesta «429 Too Many Requests», este mecanismo es particularmente eficaz: una política que reintentara inmediatamente solo mantendría la saturación, mientras que aumentar el espaciado eventualmente baja del umbral del proveedor.
Nunca omitas start_to_close_timeout
Este tiempo de espera es crítico y debe aparecer en cada actividad, sin excepción. Sin él, una actividad que se quede bloqueada —deadlock, conexión colgada, servicio que acepta la solicitud pero nunca responde— esperará indefinidamente y congelará todo el flujo de trabajo. Peor aún: no activará ningún reintento, ya que desde su perspectiva aún no ha fallado.
# MALA PRÁCTICA: sin tiempo de espera
@workflows.activity()
async def dangerous_activity(params: dict) -> dict:
# Si el servicio nunca responde, la actividad espera indefinidamente
async with httpx.AsyncClient() as client:
response = await client.get("https://api.lente.example.com/data")
return response.json()
# BUENA PRÁCTICA: tiempo de espera explícito
@workflows.activity(
start_to_close_timeout=timedelta(minutes=2)
)
async def safe_activity(params: dict) -> dict:
async with httpx.AsyncClient(timeout=90) as client:
response = await client.get("https://api.lente.example.com/data")
return response.json()
Para establecer el valor, mide primero el tiempo de ejecución normal de la actividad y añade luego un margen de dos o tres veces para cubrir casos lentos. Finalmente, asegúrate de que el tiempo de espera interno del cliente HTTP sea menor que el start_to_close_timeout —en el ejemplo anterior, 90 segundos frente a 2 minutos— para que el error se propague limpiamente desde tu código en lugar de ser cortado por la plataforma.
Idempotencia: una condición innegociable
Dado que una actividad puede reproducirse varias veces con los mismos parámetros, debe producir el mismo efecto independientemente del número de ejecuciones. Esta propiedad se llama idempotencia, y su ausencia convierte una política de reintentos en un generador de incidentes.
@workflows.activity(retry_policy_max_attempts=3)
async def add_credit(user_id: str, amount: float) -> dict:
"""PELIGROSO: si se reintenta, el crédito se añade varias veces."""
async with httpx.AsyncClient() as client:
response = await client.post(
f"https://api.billing.com/credits/add",
json={"user_id": user_id, "amount": amount}
)
return response.json()
El escenario temido es común: la API de facturación procesa la solicitud correctamente, pero la respuesta se pierde en la red. La actividad concluye con un fallo, la plataforma reintenta y el cliente recibe el crédito dos veces. Una clave de idempotencia elimina el problema al dar al servicio remoto una forma de reconocer una solicitud ya procesada.
@workflows.activity(retry_policy_max_attempts=3)
async def add_credit(user_id: str, amount: float, idempotency_key: str) -> dict:
"""CORRECTO: la clave de idempotencia evita duplicidades."""
async with httpx.AsyncClient() as client:
response = await client.post(
f"https://api.billing.com/credits/add",
json={
"user_id": user_id,
"amount": amount,
"idempotency_key": idempotency_key
}
)
return response.json()
Genera la clave en el flujo de trabajo usando workflow.uuid4(), lo que garantiza que permanezca idéntica de una reproducción a otra; un uuid.uuid4() clásico produciría un nuevo valor en cada intento y anularía toda protección. Cuando el servicio remoto no ofrece este mecanismo, existen otras dos vías: upsert en la base de datos, usando INSERT ... ON CONFLICT UPDATE en lugar de solo INSERT, o verificación previa, que implica consultar el estado antes de actuar.
Tres perfiles de configuración
Los valores se calibran según la naturaleza de la operación. Un pago o una notificación deben tener éxito rápidamente o fallar rápidamente: tiempo de espera corto, tres intentos, retroceso moderado.
@workflows.activity(
start_to_close_timeout=timedelta(seconds=30),
retry_policy_max_attempts=3,
retry_policy_backoff_coefficient=2.0,
)
async def process_payment(params: dict) -> dict:
# ...
pass
El procesamiento de larga duración, como la generación de informes o la inferencia pesada, invierte la lógica: cada intento cuesta un tiempo de cómputo significativo, por lo que autorizas menos intentos con un espaciado mayor.
@workflows.activity(
start_to_close_timeout=timedelta(minutes=15),
retry_policy_max_attempts=2,
retry_policy_backoff_coefficient=3.0,
)
async def generate_ml_report(params: dict) -> dict:
# ...
pass
Frente a una API de terceros inestable sujeta a limitación de tasa, asumes finalmente la persistencia: cinco intentos, aunque se extiendan durante varios minutos.
@workflows.activity(
start_to_close_timeout=timedelta(minutes=2),
retry_policy_max_attempts=5,
retry_policy_backoff_coefficient=2.0,
)
async def call_third_party_api(params: dict) -> dict:
# ...
pass
Puntos clave
- Configura siempre
start_to_close_timeoutpara evitar actividades bloqueadas - El retroceso exponencial (
retry_policy_backoff_coefficient) aumenta el retraso entre intentos retry_policy_max_attemptsdefine el número máximo de intentos antes del fallo definitivo- Las actividades con reintento deben ser idempotentes: mismo resultado si se ejecutan varias veces
- Usa claves de idempotencia o upserts para garantizar la idempotencia
- Adapta los tiempos de espera y el número de reintentos al tipo de operación (rápida vs. larga, estable vs. inestable)