Idempotência em automações: a chave que o retry respeita

Idempotência é o que impede o retry de criar o mesmo pedido, a mesma cobrança ou o mesmo card duas vezes. Sem uma chave de negócio estável, cada nova tentativa parece um caso novo e a automação duplica o efeito.
Rede cai, fila reentrega, pessoa clica de novo, webhook chega duas vezes. Isso é o normal da operação, não a exceção. O desenho certo trata a repetição como esperada: a primeira execução faz o efeito, as seguintes devolvem o resultado que já existe.

Qual chave identifica o caso de negócio?
A chave é o identificador que o negócio já reconhece: pedido, nota, protocolo, pagamento. Não é o ID da tentativa, o timestamp da mensagem nem um UUID gerado a cada clique. Chave que muda a cada retry não deduplica nada.
Quando o negócio não tem identificador, construa um com os campos que definem o efeito: cliente, tipo, valor e a janela combinada. Escreva a regra. “Mais ou menos o mesmo pedido” não é chave. Duas pessoas precisam chegar no mesmo identificador a partir dos mesmos dados.
O que a segunda execução devolve?
A segunda execução com a mesma chave não refaz o efeito. Ela devolve o estado atual: já criado, já cobrado, já recusado. Quem chamou consegue seguir sem saber se foi a primeira vez. Isso vale para API, fila e botão de reprocessar.
Devolver erro genérico na segunda vez faz o chamador tentar de novo e piora a duplicata. Devolver sucesso sem dizer que o efeito já existia também confunde reconciliação. A resposta carrega a chave e o estado.
Onde gravar a chave para o retry enxergar?
A gravação da chave e o efeito precisam ser uma decisão só. Se o sistema cobra e só depois anota a chave, uma queda no meio cria a cobrança sem memória. Se anota a chave e falha antes do efeito, a próxima tentativa acha que já fez e não faz.
Na prática, reserve a chave no começo com estado “em progresso”, conclua com o identificador externo e, se falhar de forma desconhecida, não apague a reserva. A tentativa seguinte lê a reserva e consulta o sistema externo antes de repetir o efeito.
| Estado da chave | O que o retry faz | O que não faz |
|---|---|---|
| Não existe | Executa o efeito e grava a chave | Não assume que é duplicata |
| Em progresso | Consulta o efeito externo antes de repetir | Não dispara outra cobrança no escuro |
| Concluída | Devolve o resultado já gravado | Não cria outro pedido |
| Recusada | Devolve a recusa original | Não reabre o caso sem uma chave nova |
Retry, fila e botão são o mesmo problema?
Sim, do ponto de vista do efeito. O timeout da API, a reentrega da fila e o analista que aperta “reprocessar” precisam cair na mesma chave. Proteção só no botão deixa a fila duplicar. Proteção só na fila deixa o reprocesso manual duplicar.
O prazo da chave também é decisão. Cobrança de um pedido vive enquanto o pedido vive. Um clique de formulário pode deduplicar por uma janela curta. Escrever “para sempre” ou “por cinco segundos” sem olhar o efeito é como não ter chave.
Como testar sem esperar a produção duplicar?
O teste envia a mesma chave duas vezes e confere que existe um efeito só. Envia duas chaves diferentes e confere que existem dois efeitos. Simula queda depois do efeito externo e antes do registro, e confere que a segunda tentativa consulta em vez de repetir.
Inclua o caso de resposta perdida: o chamador não recebeu o sucesso e tenta de novo. Esse é o retry mais comum e o que mais gera cobrança duplicada quando a chave não foi reservada. Teste de caminho feliz, uma vez só, não pega esse buraco.
Como reconciliar o que já duplicou?
Idempotência nova não apaga duplicata antiga. Antes de ligar a chave, tire um relatório do efeito repetido: dois pedidos, duas cobranças, dois cards para a mesma chave de negócio. A operação trata o passado com regra de estorno ou de merge. O fluxo novo para de aumentar o rombo.
A chave também entra no monitoramento. Um pico de “já existia” pode ser retry saudável depois de uma instabilidade, ou um cliente disparando de verdade dois pedidos. Separe as duas leituras: mesma chave é retry; chaves diferentes no mesmo cliente em segundos pode ser outra decisão de negócio.
Checklist prático
A automação aguenta retry quando a chave, o estado e o teste da segunda execução existem juntos.
- Chave de negócio estável, escrita, diferente do ID da tentativa
- Reserva da chave e efeito tratados sem janela de duplicata
- Estado em progresso que consulta o sistema externo antes de repetir
- Segunda chamada devolve o resultado já gravado, com a chave
- A mesma chave vale para API, fila e botão de reprocessar
- Prazo da chave alinhado à vida do pedido, da nota ou do protocolo
- Teste de duas chamadas iguais e de resposta perdida
- Relatório do que já duplicou antes de ligar a proteção nova
Erros comuns
Duplicata de cobrança e de card quase sempre nasce de uma destas escolhas.
- Usar timestamp ou UUID novo como se fosse chave de negócio
- Proteger só o botão e deixar a fila reentregar
- Gravar a chave só depois do efeito externo
- Apagar a reserva quando a resposta se perde no caminho
- Devolver erro genérico na segunda execução e provocar outro retry
- Testar o fluxo uma vez e considerar o retry coberto
- Ignorar a duplicata histórica e só “ligar a trava” para a frente
- Tratar duas chaves diferentes do mesmo cliente como bug técnico sem olhar o negócio
Onde a chave entra no fluxo?
Em automações de processos, retry é parte do desenho. A chave de negócio é o que faz a segunda tentativa ser segura.