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

Dois volumes iguais, um aceito pelo encaixe e o outro devolvido como duplicado

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.

Um envelope com chave entrando na fechadura e um segundo envelope idêntico voltando
A segunda tentativa com a mesma chave de negócio não repete o efeito.

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 chaveO que o retry fazO que não faz
Não existeExecuta o efeito e grava a chaveNão assume que é duplicata
Em progressoConsulta o efeito externo antes de repetirNão dispara outra cobrança no escuro
ConcluídaDevolve o resultado já gravadoNão cria outro pedido
RecusadaDevolve a recusa originalNã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.

Perguntas frequentes

▸Idempotência é o mesmo que travar o botão?

Não. Travar o botão evita o clique duplo naquela tela. A fila, o webhook e o timeout continuam podendo repetir o efeito. A chave de negócio precisa valer em todos os caminhos que executam a mesma ação.

▸Posso usar o ID gerado em cada tentativa?

Não, se a pergunta é “esse pedido já foi cobrado?”. ID de tentativa muda quando o retry acontece, então as duas execuções parecem casos novos. A chave tem de sair do pedido, da nota ou do protocolo.

▸O que fazer se a cobrança ocorreu e o registro não?

A chave fica em progresso e a tentativa seguinte consulta o sistema de pagamento antes de cobrar de novo. Apagar a reserva e recomeçar é o caminho da cobrança duplicada. O estado intermediário existe para esse buraco.

▸Por quanto tempo a chave precisa viver?

Pelo tempo em que repetir o efeito ainda seria erro. Um pedido vive com o pedido. Um formulário de contato pode deduplicar numa janela curta. O prazo é decisão de negócio, escrita junto com a chave.

▸Como saber se a proteção está funcionando?

Pelo teste da segunda chamada com a mesma chave, inclusive quando a primeira resposta se perdeu, e pelo monitoramento de efeitos duplicados. Volume de retry, sozinho, pode ser instabilidade saudável.

▸Dá para corrigir duplicata só com a chave nova?

A chave nova impede a próxima duplicata. O que já foi cobrado ou aberto duas vezes precisa de estorno, merge ou baixa operacional. Ligar a trava sem olhar o passado deixa o erro antigo na base.

Deixe um comentário

O seu endereço de e-mail não será publicado. Campos obrigatórios são marcados com *