Ga naar hoofdinhoud
Nederlands— Kies een taal
Menu

Retry Policy

Les 12 van 14 Bijgewerkt op 29 juli 2026 Gevorderd
Op deze pagina
  1. Waarom retries essentieel zijn
  2. Een retry policy configureren
  3. Laat start_to_close_timeout nooit weg
  4. Idempotentie: een niet-onderhandelbare voorwaarde
  5. Drie configuratieprofielen
  6. Belangrijkste punten

Waarom retries essentieel zijn

In een gedistribueerd systeem zijn tijdelijke fouten onvermijdelijk: netwerktime-outs, overschreden rate limits, tijdelijk niet-beschikbare services. Geen van deze storingen wijst op een bug in uw code, toch kan elk ervan een proces doen falen als niets de schok opvangt. Een retry policy laat uw activities deze fouten overleven zonder handmatige tussenkomst; het platform start ze automatisch opnieuw op volgens de configuratie die u voor elke activity definieert.

Een retry policy configureren

De decorator @workflows.activity() accepteert parameters die dit gedrag sturen. Hier is een activity voor een externe API-aanroep, goed uitgerust voor veerkracht.

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:
    """Calls an external API with automatic retry."""
    async with httpx.AsyncClient(timeout=60) as client:
        response = await client.post(url, json=data)
        response.raise_for_status()
        return response.json()

Drie parameters, drie complementaire rollen.

  • start_to_close_timeout — Maximale duur voor één uitvoeringspoging. Als de activity binnen deze termijn niet voltooid is, wordt deze als mislukt beschouwd en wordt een nieuwe poging gestart.

  • retry_policy_max_attempts — Maximum aantal pogingen. De standaardwaarde hangt af van het platform. Na dit aantal pogingen faalt de activity definitief en ontvangt de workflow een foutmelding.

  • retry_policy_backoff_coefficient — Vermenigvuldiger voor de vertraging tussen pogingen. Met een coëfficiënt van 2,0 verdubbelen de vertragingen bij elke poging (1s, 2s, 4s, 8s…). Dit is exponentiële backoff.

Dit backoff-mechanisme verdient aandacht omdat het doel niet alleen wachten is: het geeft de worstelende service tijd om te herstellen in plaats van deze te bestoken. Het verloop van een aanroep die uiteindelijk slaagt, illustreert dit duidelijk.

Attempt 1: immediate execution
  → Failure (network timeout)
  → Wait 1 second

Attempt 2: execution
  → Failure (service unavailable)
  → Wait 2 seconds (1 × 2.0)

Attempt 3: execution
  → Failure (rate limit)
  → Wait 4 seconds (2 × 2.0)

Attempt 4: execution
  → Success!

Bij een “429 Too Many Requests”-respons is dit mechanisme bijzonder effectief: een policy die onmiddellijk opnieuw probeert, zou de verzadiging alleen maar in stand houden, terwijl het vergroten van de tussenpozen uiteindelijk onder de drempel van de provider zakt.

Laat start_to_close_timeout nooit weg

Deze time-out is cruciaal en moet op elke activity staan, zonder uitzondering. Zonder dit wacht een activity die vastloopt—deadlock, hangende connectie, service die het verzoek accepteert maar nooit antwoordt—oneindig lang en bevriest het de hele workflow. Erger nog: het triggert geen retry, omdat het vanuit zijn perspectief nog niet gefaald is.

# BAD PRACTICE: no timeout
@workflows.activity()
async def dangerous_activity(params: dict) -> dict:
    # If the service never responds, the activity waits indefinitely
    async with httpx.AsyncClient() as client:
        response = await client.get("https://api.lente.example.com/data")
    return response.json()

# GOOD PRACTICE: explicit timeout
@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()

Om de waarde in te stellen, meet u eerst de normale uitvoeringstijd van de activity en voegt u vervolgens een marge van twee tot drie keer toe voor trage gevallen. Zorg er ten slotte voor dat de interne HTTP-client time-out lager blijft dan de start_to_close_timeout—in het bovenstaande voorbeeld 90 seconden versus 2 minuten—zodat de fout schoon vanuit uw code propagateert in plaats van door het platform afgekapt te worden.

Idempotentie: een niet-onderhandelbare voorwaarde

Omdat een activity meerdere keren met dezelfde parameters opnieuw kan worden afgespeeld, moet deze hetzelfde effect produceren, ongeacht het aantal uitvoeringen. Deze eigenschap heet idempotentie; het ontbreken ervan verandert een retry policy in een incidentengenerator.

@workflows.activity(retry_policy_max_attempts=3)
async def add_credit(user_id: str, amount: float) -> dict:
    """DANGEROUS: if retried, credit is added multiple times!"""
    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()

Het gevreesde scenario komt vaak voor: de billing-API verwerkt het verzoek correct, maar de respons raakt kwijt op het netwerk. De activity concludeert een fout, het platform probeert het opnieuw en de klant krijgt twee keer krediet. Een idempotentie-sleutel elimineert het probleem door de externe service een manier te geven een reeds verwerkt verzoek te herkennen.

@workflows.activity(retry_policy_max_attempts=3)
async def add_credit(user_id: str, amount: float, idempotency_key: str) -> dict:
    """CORRECT: idempotency key prevents duplication."""
    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()

Genereer de sleutel in de workflow met workflow.uuid4(), wat garandeert dat deze identiek blijft van replay tot replay—een klassieke uuid.uuid4() zou bij elke poging een nieuwe waarde produceren en alle bescherming tenietdoen. Wanneer de externe service dit mechanisme niet biedt, zijn er twee andere paden: upsert in de database, gebruikmakend van INSERT ... ON CONFLICT UPDATE in plaats van alleen INSERT, of pre-check verificatie, wat inhoudt dat u de status bevraagt voordat u handelt.

Drie configuratieprofielen

Waarden worden gekalibreerd op basis van de aard van de bewerking. Een betaling of melding moet snel slagen of snel falen: korte time-out, drie pogingen, matige backoff.

@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

Langdurige verwerking, zoals rapportgeneratie of zware inferentie, draait de logica om: elke poging kost aanzienlijke rekentijd, dus autoriseert u minder pogingen met bredere tussenpozen.

@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

Bij een instabiele third-party API die onderhevig is aan rate limiting, kiest u uiteindelijk voor volharding: vijf pogingen, zelfs als dit enkele minuten beslaat.

@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

Belangrijkste punten

  • Configureer altijd start_to_close_timeout om blokkerende activities te voorkomen
  • Exponentiële backoff (retry_policy_backoff_coefficient) verhoogt de vertraging tussen pogingen
  • retry_policy_max_attempts definieert het maximum aantal pogingen vóór definitieve mislukking
  • Activities met retry moeten idempotent zijn—zelfde resultaat bij meerdere uitvoeringen
  • Gebruik idempotentie-sleutels of upserts om idempotentie te garanderen
  • Pas time-outs en retry-aantallen aan op het type bewerking (snel vs. lang, stabiel vs. instabiel)