Ir al contenido principal
Español— Elegir un idioma
Menú

Política de reintentos

Lección 12 de 14 Actualizado el 29 de julio de 2026 Avanzado
En esta página
  1. Por qué los reintentos son esenciales
  2. Configuración de una política de reintentos
  3. Nunca omitas start_to_close_timeout
  4. Idempotencia: una condición innegociable
  5. Tres perfiles de configuración
  6. Puntos clave

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_timeout para evitar actividades bloqueadas
  • El retroceso exponencial (retry_policy_backoff_coefficient) aumenta el retraso entre intentos
  • retry_policy_max_attempts define 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)