Idempotência

Todo POST exige o cabeçalho Idempotency-Key: um texto seu, de até 255 caracteres, que identifica aquele pedido.

Idempotency-Key: pedido-1042

• Repetir o mesmo pedido com a mesma chave devolve a mesma resposta (mesmo status e a cobrança atual), sem criar nada de novo. Caiu a conexão no meio? Repita sem medo.
• Exceção a favor de você: um PIX criado com 202 (ainda emitindo) que o banco já emitiu responde 201 na repetição, com o copia e cola.
• Usar a mesma chave com um corpo diferente é recusado (422, campo Idempotency-Key): a chave identifica um pedido só.
• A chave vale por 24 horas.
• Sem o cabeçalho: 400 IDEMPOTENCY_KEY_REQUIRED.

Dica: use algo que já identifique a operação no seu sistema, como pedido-1042 para criar e devolucao-1042-1 para devolver.