POST, PUT, PATCH, DELETE) precisa do header HTTP Idempotency-Key. Sem ele a resposta é 422 idempotency_key_required e nada é executado.
Use uma chave única para cada operação. Se precisar repetir a mesma operação por falha de rede, envie a mesma chave e o mesmo corpo: a API devolve a resposta guardada da primeira vez, sem executar de novo.
Um UUID é uma boa escolha para a chave.
O que conta como “o mesmo corpo”
A comparação é sobre o método, o caminho e o corpo bruto da requisição, os três juntos. Reenviar o mesmo JSON com as chaves em outra ordem, ou com outra formatação, conta como corpo diferente e responde409.
A chave é guardada por conta: duas contas podem usar o mesmo valor sem se cruzarem.
A resposta guardada vale por 24 horas. Depois disso a mesma chave volta a ser uma chave nova, e o reenvio executa a operação outra vez.
Erros comuns
A requisição altera dados, mas foi enviada sem
Idempotency-Key.Já existe uma requisição com essa chave em processamento. Aguarde alguns instantes e tente de novo com a mesma chave.
A chave já foi usada com outro corpo. Gere uma chave nova para uma operação diferente.
O que fica guardado
Uma resposta só é guardada quando a operação produziu um resultado utilizável, o que inclui as recusas: um404 e um 422 de validação ficam guardados e voltam iguais no reenvio da mesma chave.
Um 5xx e uma exceção não ficam. A chave é liberada, então o reenvio executa a operação de verdade, que é o que você quer depois de uma falha do servidor.
O 403 também não é replicado como resposta: o escopo é conferido antes da idempotência, justamente para que conceder a permissão que faltava mude a resposta na hora.
Não reutilize a mesma
Idempotency-Key para operações diferentes.