Como você torna um endpoint de escrita seguro para retry?

Dê ao cliente uma chave de idempotência, guarde essa chave junto do resultado da primeira escrita bem sucedida, e devolva esse resultado guardado em qualquer repetição. Imponha unicidade no nível do banco de dados para que duplicatas concorrentes colidam em vez de escreverem duas vezes. Delimite as chaves por cliente, expire depois de uma janela sensata, e use a chave de negócio natural, como um id de pedido, como âncora de deduplicação sempre que existir uma.

O cliente gera uma chave de idempotência, normalmente um UUID, e manda como header. Do lado do servidor eu mantenho uma tabela com chave em id do cliente mais essa chave, com uma constraint de unicidade, e eu escrevo a chave e a resposta na mesma transação da escrita de negócio. Uma repetição então bate na constraint de unicidade ou acha a linha guardada e simplesmente reproduz a resposta original, então retries saem de graça. Dois detalhes importam. Primeiro, a unicidade tem que morar no banco, porque se você faz um select e depois um insert, dois retries concorrentes passam os dois pela checagem. Segundo, você precisa decidir o que fazer quando a segunda requisição chega enquanto a primeira ainda está rodando. A gente retornava 409 com um Retry-After em vez de bloquear, o que mantinha o nosso pool de conexões saudável. Eu também guardo um hash do corpo da requisição, para que reusar uma chave com conteúdo diferente seja rejeitado em vez de devolver silenciosamente a resposta errada.