Idempotency
Networks drop answers. An idempotency key lets you send a write again without earning, redeeming or sending a code twice.
The header
Every POST needs an Idempotency-Key header: 1 to 255 characters, unique for each new action. A UUID is a good choice. Keys starting with nimbu:, dash:, staff:, seed: are kept for Nimbuu.
Idempotency-Key: 6f1c2a9e-3b7d-4e0f-9a51-2c8d7e4b1f06
Sending it again
- Same key, same body: you get the first answer again, with the header
Idempotent-Replayed: true. Nothing new is written. This is how to retry after a timeout. - Same key, different body: 409
idempotency_conflict. A retry must send exactly the same body,otp_verificationincluded. - Two requests at once with one key: the second waits for the first, then gets its answer.
- A request that failed (any error) is not remembered, so sending it again with the same key runs it again. That is safe, because nothing was written.
We keep keys for 24 hours. Secret and publishable keys of one shop never share keys, and neither do two shops.