Projetar operações idempotentes e repetições seguras

Objetivo

Um cliente cuja requisição termina em timeout deve poder repeti-la sem risco: sem pedido duplicado, sem pagamento duplicado, sem artigo duplicado.

Pré-requisitos

A RFC 9110 chama um método de idempotente quando o efeito pretendido no servidor de várias requisições idênticas é o mesmo que o de uma única; PUT, DELETE e os métodos seguros (GET, HEAD, OPTIONS, TRACE) são idempotentes, POST não. A mesma RFC estabelece que um cliente não deve repetir automaticamente uma requisição com método não idempotente, a menos que saiba que a semântica é de fato idempotente. Para POST, o rascunho do IETF «The Idempotency-Key HTTP Header Field» (grupo de trabalho HTTPAPI; versão 07 de outubro de 2025, em setembro de 2026 expirado e não publicado como RFC) descreve o cabeçalho que a Stripe e outros provedores utilizam. São necessários um armazenamento para um pequeno registro por chave e clientes que gerem uma chave única para cada operação lógica.

Passos

1. Escolher os métodos conforme a RFC 9110: alterar com PUT em um endereço conhecido, excluir com DELETE; ambos podem ser repetidos sem mecanismo adicional.
2. Para requisições POST que criam recursos, aceitar um cabeçalho Idempotency-Key. O rascunho recomenda um UUID ou um identificador aleatório equivalente; a Stripe sugere UUIDs V4, permite até 255 caracteres e desaconselha usar dados sensíveis como chave.
3. Na primeira chegada, guardar a chave junto com uma impressão digital da requisição (hash sobre o caminho e o corpo), a conta e o resultado (status, corpo da resposta) – na mesma transação da própria operação ou sob um bloqueio na chave, para que duas repetições simultâneas não passem as duas.
4. Se a chave chegar de novo com a mesma impressão digital, devolver a resposta guardada sem alterações. Se a chave for a mesma, mas o corpo diferente, responder 422, como prevê o rascunho; se a requisição original ainda estiver em processamento, responder 409.
5. Apagar as chaves após um prazo documentado; a Stripe descreve uma remoção após no mínimo 24 horas e trata como nova requisição uma chave reutilizada depois disso.
6. Registrar na documentação da API o formato da chave, o prazo e o comportamento em caso de conflito, para que clientes e agentes possam confiar nisso em vez de adivinhar.

Resultado esperado

Um cliente que repete a requisição com a mesma chave após um timeout obtém exatamente um recurso criado e a mesma resposta nas duas vezes.

Limites e base de verificação

A idempotência cobre o estado do próprio servidor, não os efeitos colaterais em sistemas de terceiros (por exemplo, um e-mail enviado duas vezes por um serviço a jusante). As chaves devem ser separadas por conta, caso contrário clientes diferentes entram em colisão. O rascunho não é uma RFC e está atualmente expirado; as afirmações sobre o cabeçalho e os códigos de status seguem o rascunho e a documentação citada da Stripe, e não se afirma nenhuma medição.