Idempotency
An idempotency key stops a retry from writing twice. Send one with a write, and the same request sent again returns the first result.
The key is a field in the body, never a header. An Idempotency-Key header is ignored and the
write happens twice.
| Write | Where the key goes |
|---|---|
POST /v1/events | On each item, so one call can carry a thousand of them. |
POST /v1/points/adjustments | On the body. |
POST /v1/marketplace-items/{marketplaceItemKey}/purchases | On the body. |
At most 200 characters, and it is yours to choose. Use something your own system already has: the order id, the ticket number, the id of the job that sent it.
What a replay returns
The original result. A replayed purchase returns the purchase that already happened and takes no more points.
A key belongs to one write
The same key used for something else is refused rather than replayed.
An event. The key is per player and per event, so the same key on a different event is a separate write.
Points. Adjustments and purchases share one set of keys per player. A key already used by a
purchase, or by an adjustment for a different amount, is refused with
points_adjustment.idempotency_key_conflict.
A purchase. A key already used for a different listing is refused with
marketplace_purchase.idempotency_key_conflict.
Without a key
Nothing is matched up. A retried batch writes its events again, a retried adjustment moves the balance again, and a retried purchase charges the player again.