Idempotência
Repita uma compra com segurança, sem comprar duas vezes.
Um erro de rede pode deixar você sem saber se uma compra foi concluída. Por isso, todo POST /offsets exige um cabeçalho Idempotency-Key: um valor único por compra, como um UUID.
Idempotency-Key: 7f8d0c6e-2b1a-4e9f-9d3c-5a6b7c8d9e0fO que acontece em uma nova tentativa
| Você envia | Você recebe |
|---|---|
| Uma chave nova | Uma nova compra (201). |
| A mesma chave e o mesmo corpo | A primeira compra de novo (201), com Idempotent-Replayed: true. Nada é comprado duas vezes. |
| A mesma chave e um corpo diferente | 409 idempotency_key_reused. Use uma chave nova para uma nova compra. |
A repetição retorna a compra no estado atual dela, então o status pode ter mudado de processing para placed.
Bom saber
- As chaves têm de 1 a 255 caracteres ASCII imprimíveis, e nós as guardamos para sempre, por modo.
- A ordem das chaves e os espaços no corpo não importam:
{"kg":1,"reference":"a"}e{ "reference": "a", "kg": 1 }são a mesma requisição. - Uma compra que falha (por exemplo,
402 insufficient_balanceou um erro de validação) não armazena nada. Depois de adicionar saldo, você pode tentar de novo com a mesma chave. - Duas requisições com a mesma chave no mesmo instante são seguras: uma faz a compra, e a outra recebe a repetição.