Classificar Erro Antes de Tentar de Novo

Problema

O assistente agenda um Pix. A API do banco devolve timeout. O código tenta de novo, cinco vezes, com a mesma chamada. O banco tinha registrado a primeira. Cinco Pix saem. Todo erro dispara outra tentativa, inclusive os que nunca vão dar certo, e efeitos acabam duplicados. É o smell Retry Cego.

Solução

Antes de tentar de novo, classifique o erro. Erros transitórios (rede, limite de taxa, indisponibilidade momentânea) têm retry com espera crescente e limite. Erros permanentes (validação, permissão, saldo, regra de negócio) voltam para quem chamou com uma explicação. Toda chamada com efeito leva uma chave de idempotência.

Antes e depois

-for attempt in range(5):
-    try:
-        return bank.schedule_pix(key, amount, date)
-    except Exception:
-        time.sleep(2 ** attempt)
+TRANSIENT = {"TIMEOUT", "CONNECTION_RESET", "RATE_LIMITED", "SERVICE_UNAVAILABLE"}
+
+def schedule_pix(key, amount, date, request_id):
+    for attempt in range(3):
+        try:
+            return bank.schedule_pix(key, amount, date, idempotency_key=request_id)
+        except BankError as e:
+            if e.code not in TRANSIENT:
+                return {"ok": False, "error": e.code, "retryable": False,
+                        "message": HUMAN_MESSAGES.get(e.code, e.message)}
+            time.sleep(min(2 ** attempt + random.random(), 10))   # espera com jitter
+    return {"ok": False, "error": "UNAVAILABLE", "retryable": True,
+            "message": "O banco está instável. Tente de novo em alguns minutos."}

Antes: qualquer erro, mesma resposta.

flowchart LR
  C["1. Chamada"]:::tool --> E{"2. Erro?"}
  E -->|"qualquer"| C

Depois: o tipo do erro decide.

flowchart LR
  C["1. Chamada com chave de idempotência"]:::tool --> E{"2. Tipo do erro"}
  E -->|"transitório"| W["3. Esperar e tentar, com limite"]:::tool
  W --> C
  E -->|"permanente"| R(["4. Explicar a quem chamou"]):::io
  E -->|"ok"| OK(["5. Resultado"]):::io

1. Toda chamada com efeito carrega uma chave que o serviço usa para não repetir o efeito.
2. O erro é classificado pelo código ou status, nunca pelo texto da mensagem.
3. Só erros transitórios voltam a ser tentados, com espera crescente e teto.
4. Erros permanentes viram uma resposta clara, que o modelo ou o usuário pode usar.
5. O sucesso acontece uma vez, mesmo com retries.

Por que funciona

Repetir só ajuda quando a causa do erro pode desaparecer sozinha. Rede instável e limite de taxa passam; saldo insuficiente e chave Pix inválida, não. Classificar evita gastar tentativas no que não vai funcionar, e evita que uma tentativa “dê certo” na hora errada.

A chave de idempotência resolve o caso mais perigoso: a chamada que deu certo no servidor, mas cuja resposta se perdeu na rede. Sem a chave, o retry repete o efeito. Com ela, o servidor reconhece a repetição e devolve o resultado da primeira vez. APIs de pagamento sérias (a do Stripe, as de Pix dos bancos) aceitam essa chave por esse motivo.

Num agente, o erro permanente bem explicado também ajuda o modelo: em vez de repetir schedule_pix com os mesmos argumentos, ele informa o usuário ou muda de caminho. Classifique pelo código (INSUFFICIENT_FUNDS, 400, 429), nunca por um if "timeout" in str(e). Mensagens mudam; códigos não.

Exemplo trabalhado: timeout que era sucesso

Entrada: agendar R$ 250 para amanhã, request_id=chk_9f3a. O banco processa, a rede cai antes da resposta. Sem chave, o retry cria chk novo e agenda de novo. Com chave, o segundo POST devolve o mesmo agendamento. Saída no trace: attempts=2, effect=1.

Classificar o timeout como transitório está certo. O que impede o duplicado é a chave nascida com a intenção do usuário, não com a tentativa.

Checagem +20 XP de primeiraA API devolve 400 com INSUFFICIENT_FUNDS. Seu loop faz retry com espera crescente, porque ‘às vezes o saldo muda’. O que isso causa?

Uma segunda chance justa: o usuário pode ter depositado nesse intervalo

Retry em erro permanente: gasta tentativas, atrasa, e não corrige saldo. Devolva a mensagem ao modelo ou ao usuário

Nada, se houver chave de idempotência o banco ignora as tentativas extras

Passo a passo seguro

0. Meça. Levante nos logs os erros mais comuns de cada dependência e quantos retries cada um gerou. Procure efeitos duplicados (dois Pix com o mesmo pedido).
1. Classifique os códigos de erro de cada serviço em transitórios e permanentes. Na dúvida, trate como permanente.
2. Acrescente chave de idempotência a todas as chamadas com efeito, gerada uma vez por intenção do usuário.
3. Implemente o retry só para transitórios, com espera crescente, jitter (um pouco de acaso na espera, para mil clientes não baterem no mesmo segundo) e teto. Respeite Retry-After quando o serviço mandar.
4. Escreva mensagens úteis para erros permanentes, para o modelo e para o usuário.
5. Detecte repetição no agente: a mesma ferramenta com os mesmos argumentos depois de erro permanente encerra o caminho.
6. Meça de novo: retries por erro, efeitos duplicados (devem ir a zero) e tempo até a resposta.

Armadilha: três camadas de retry

O SDK do provedor repete duas vezes. A sua função repete três. O loop do agente chama a ferramenta de novo. Nove tentativas, e ninguém combinou o teto. Desligue o retry do SDK (max_retries=0) nas chamadas em que você classifica. Um só lugar decide.

Outra armadilha: gerar uuid4() dentro do for attempt. Cada volta é uma chave nova, e a idempotência some. A chave nasce com o clique, o ticket, o request_id da conversa.

Se o serviço não aceita chave, consulte o estado antes de repetir (“já existe um Pix com este request_id?”). Sem consulta, não repita efeito.

Checagem +20 XP de primeiraVocê gera idempotency_key=str(uuid4()) no início de cada volta do for attempt. O banco aceita a chave. Por que os Pix ainda duplicam num timeout?

O banco ignora a chave em timeout; idempotência só vale para 200

uuid4 não é determinístico o bastante; use um hash do valor e da chave Pix

Cada tentativa manda uma chave diferente, então o banco vê pedidos novos. A chave tem que nascer com a intenção, fora do loop

Riscos

• Classificação errada. Um erro permanente tratado como transitório volta ao problema original. Revise a lista quando o serviço mudar.
• Chave de idempotência gerada a cada tentativa. Assim ela não protege nada.
• Serviço que não suporta idempotência. Nesse caso, consulte o estado antes de repetir.
• Retries empilhados. O SDK repete, a sua função repete e o agente repete. Defina um só lugar responsável por retry. Combine com Adicionar Caminho de Fallback quando o transitório persiste: depois do teto, disjuntor, não mais uma volta.

Desafio

Classifique estes erros de uma API de envio de email e diga o que fazer com cada um.

429 Too Many Requests
400 Invalid recipient address
503 Service Unavailable
401 Invalid API key
409 Duplicate idempotency key (message already sent)

Ver solução

• 429: transitório. Esperar (respeitando Retry-After) e tentar de novo, com limite.
• 400 endereço inválido: permanente. Informar ao modelo ou ao usuário que o endereço precisa ser corrigido.
• 503: transitório. Retry com espera; se persistir, abrir o disjuntor e usar o fallback.
• 401: permanente e de configuração. Não repetir; alertar o time, porque nenhuma chamada vai funcionar.
• 409 chave duplicada: sucesso disfarçado. O email já foi enviado; tratar como resultado positivo, sem reenviar.

Relacionados

• Trata o smell Retry Cego.
• Quando o transitório persiste: Adicionar Caminho de Fallback.
• Efeito que não deveria sequer ser retentado sem pessoa: Pedir Aprovação Antes do Efeito.

Teste seu entendimento

Checagem +20 XP de primeiraO agente chama schedule_pix, recebe INVALID_PIX_KEY, e chama de novo com os mesmos argumentos no passo seguinte. Qual peça desta refatoração faltou no agente?

Mais retries no SDK, porque chave inválida às vezes é atraso de DNS

Detector de repetição: mesma ferramenta, mesmos argumentos, depois de erro permanente, encerra o caminho e explica

Uma chave de idempotência nova a cada chamada do agente, para o banco aceitar a correção

Checagem +20 XP de primeiraO provedor devolve 429 com cabeçalho Retry-After: 20. Seu backoff estava em 2s, 4s, 8s. O que você faz nesta tentativa?

Esperar 20s (o que o serviço pediu) e só então retentar, contando no teto

Ignorar o cabeçalho e seguir 2s, 4s, 8s, que é a política interna

Abrir o disjuntor na hora, porque 429 é queda do provedor

Checagem +20 XP de primeiraUm 409 Duplicate idempotency key chega depois de um timeout. O email já foi enviado. Como o código trata?

Como erro permanente: avisar o usuário que falhou, para ele reenviar se quiser

Como transitório: retentar com a mesma chave até virar 200

Como sucesso disfarçado: devolver ok ao modelo, sem novo envio, e registrar a reconciliação no trace