Confiabilidade
Idempotência
Reenvie uma operação sem disparar a mesma mensagem duas vezes.
Inclua Idempotency-Key em todo POST. A chave deve ter de 8 a 128 caracteres e ser única para cada mensagem lógica.
Idempotency-Key: order-1234-shipping-notice-v1Se a primeira resposta se perder, repita a requisição com a mesma chave e o mesmo payload. Quando a operação já tiver sido concluída, a API devolve o resultado armazenado com:
{
"idempotencyReplayed": true
}Não reutilize uma chave para outro conteúdo
Associe a chave ao evento de negócio, não à tentativa HTTP. Uma nova mensagem exige uma nova chave.
O alias legado X-Idempotency-Key continua aceito, mas novas integrações devem usar o header padrão.