Ir para o conteúdo principal
Português— Escolher um idioma
Menu

Política de Retentativas

Aula 12 de 14 Atualizada a 29 de julho de 2026 Avancado
Nesta página
  1. Por que as retentativas são essenciais
  2. Configurar uma política de retentativas
  3. Nunca omitir o start_to_close_timeout
  4. Idempotência: uma condição não negociável
  5. Três perfis de configuração
  6. Pontos-chave

Por que as retentativas são essenciais

Num sistema distribuído, os erros transitórios são inevitáveis: tempos limite de rede excedidos, limites de taxa ultrapassados, serviços temporariamente indisponíveis. Nenhuma destas falhas indica um erro no seu código, mas qualquer uma delas pode causar a falha de um processo se nada absorver o impacto. Uma política de retentativas permite que as suas atividades sobrevivam a estes erros sem intervenção manual, fazendo com que a plataforma as relance automaticamente de acordo com a configuração que definir para cada atividade.

Configurar uma política de retentativas

O decorador @workflows.activity() aceita parâmetros que governam este comportamento. Eis uma atividade de chamada a uma API externa devidamente preparada para a resiliência.

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()

Três parâmetros, três funções complementares.

  • start_to_close_timeout — Duração máxima para uma única tentativa de execução. Se a atividade não for concluída dentro deste prazo, é considerada falhada e uma nova tentativa é lançada.

  • retry_policy_max_attempts — Número máximo de tentativas. O valor padrão depende da plataforma. Após este número de tentativas, a atividade falha definitivamente e o fluxo de trabalho recebe um erro.

  • retry_policy_backoff_coefficient — Multiplicador para o atraso entre tentativas. Com um coeficiente de 2,0, os atrasos duplicam a cada tentativa (1s, 2s, 4s, 8s…). Isto é um recuo exponencial (exponential backoff).

Este mecanismo de recuo merece atenção porque o seu objetivo não é apenas esperar: dá tempo ao serviço em dificuldades para se recuperar, em vez de o sobrecarregar. A progressão de uma chamada que acaba por ter sucesso ilustra isto claramente.

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!

Perante uma resposta “429 Too Many Requests”, este mecanismo é particularmente eficaz: uma política que retentasse imediatamente apenas sustentaria a saturação, enquanto que o aumento do espaçamento acaba por baixar abaixo do limiar do fornecedor.

Nunca omitir o start_to_close_timeout

Este tempo limite é crítico e deve aparecer em todas as atividades, sem exceção. Sem ele, uma atividade que fique bloqueada — deadlock, ligação pendente, serviço que aceita o pedido mas nunca responde — espera indefinidamente e congela todo o fluxo de trabalho. Pior ainda: não desencadeia nenhuma retentativa, pois, na sua perspetiva, ainda não falhou.

# 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()

Para definir o valor, meça primeiro o tempo de execução normal da atividade e, em seguida, adicione uma margem de duas a três vezes para cobrir casos lentos. Finalmente, assegure-se de que o tempo limite interno do cliente HTTP permanece inferior ao start_to_close_timeout — no exemplo acima, 90 segundos contra 2 minutos — para que o erro se propague limparmente a partir do seu código, em vez de ser cortado pela plataforma.

Idempotência: uma condição não negociável

Uma vez que uma atividade pode ser reproduzida várias vezes com os mesmos parâmetros, deve produzir o mesmo efeito, independentemente do número de execuções. Esta propriedade chama-se idempotência e a sua ausência transforma uma política de retentativas num gerador de incidentes.

@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()

O cenário temido é comum: a API de faturação processa o pedido corretamente, mas a resposta perde-se na rede. A atividade conclui como falhada, a plataforma retenta e o cliente é creditado duas vezes. Uma chave de idempotência elimina o problema, dando ao serviço remoto uma forma de reconhecer um pedido já processado.

@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()

Gere a chave no fluxo de trabalho usando workflow.uuid4(), o que garante que permanece idêntica de uma reprodução para outra — um uuid.uuid4() clássico produziria um novo valor em cada tentativa e cancelaria toda a proteção. Quando o serviço remoto não oferece este mecanismo, existem outras duas vias: upsert na base de dados, usando INSERT ... ON CONFLICT UPDATE em vez de apenas INSERT, ou verificação prévia, que envolve consultar o estado antes de agir.

Três perfis de configuração

Os valores calibram-se de acordo com a natureza da operação. Um pagamento ou notificação deve ter sucesso rapidamente ou falhar rapidamente: tempo limite curto, três tentativas, recuo 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

Processamento de longa duração, como geração de relatórios ou inferência pesada, inverte a lógica: cada tentativa custa um tempo de computação significativo, pelo que autoriza menos tentativas com um espaçamento mais amplo.

@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

Perante uma API de terceiros instável sujeita a limitação de taxa, assume finalmente a persistência: cinco tentativas, mesmo que se estenda por vários 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

Pontos-chave

  • Configure sempre o start_to_close_timeout para evitar atividades bloqueadas
  • O recuo exponencial (retry_policy_backoff_coefficient) aumenta o atraso entre tentativas
  • retry_policy_max_attempts define o número máximo de tentativas antes da falha definitiva
  • Atividades com retentativa devem ser idempotentes — mesmo resultado se executadas várias vezes
  • Utilize chaves de idempotência ou upserts para garantir a idempotência
  • Adapte os tempos limite e as contagens de retentativa ao tipo de operação (rápida vs. longa, estável vs. instável)