Idempotência
Todo POST, PATCH e DELETE exige o cabeçalho Idempotency-Key: um valor
único por operação, por exemplo um UUID gerado pelo seu sistema.
Idempotency-Key: 2f1d9a52-0b6c-4c3e-9d8e-7a1b2c3d4e5f- Repetir o mesmo pedido com a mesma chave em até 24 h devolve a mesma
resposta, sem executar de novo (cabeçalho
Idempotent-Replayed: true). Use isso para tentar de novo com segurança depois de um erro de rede. - A mesma chave com outro corpo responde
409 idempotency_conflict. - Enquanto o primeiro pedido ainda executa, responde
409 request_in_progress. - Recusa passageira (
retryable: true, como503) libera a chave: a repetição executa de novo. - Se o resultado ficou incerto (por exemplo, o provedor não respondeu), a resposta
é
202com"status": "unknown"e a repetição com a mesma chave responde409 request_outcome_unknown. Nada é executado duas vezes. Consulte o recurso antes de tentar com outra chave.
Boa prática
Seção intitulada “Boa prática”Gere a chave a partir do que a operação é no seu sistema (por exemplo
pedido-1234-saiu): assim um reenvio do seu próprio processo nunca manda a
mesma mensagem duas vezes.