Pular para o conteúdo

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, como 503) libera a chave: a repetição executa de novo.
  • Se o resultado ficou incerto (por exemplo, o provedor não respondeu), a resposta é 202 com "status": "unknown" e a repetição com a mesma chave responde 409 request_outcome_unknown. Nada é executado duas vezes. Consulte o recurso antes de tentar com outra chave.

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.