API reference

Idempotency

A network can fail after Uncart has done what you asked but before you have its answer. An Idempotency-Key header lets you send the same write again. Uncart does the work once and answers the repeat with the answer it gave the first time.

How to use it

Every write takes the header (POST, PUT, PATCH and DELETE), and every POST needs it. Make a new random value, such as a UUID, for each new request, and keep it with the request until you have an answer. Send the same value when you send the same request again.

The value is 1 to 255 visible ASCII characters. A POST without one gets 400 idempotency_key_required.

What Uncart does with it

Uncart keeps each key for 24 hours after the first request that used it.

  • The same request gets the first answer again, word for word, with the header Idempotent-Replayed: true. Nothing is done twice.
  • A request with another method, address or body gets 422 idempotency_key_reused, and nothing is done.
  • While the first request is still being handled, a repeat gets 409 idempotency_in_progress. Wait for its Retry-After and try again.

An answer of 500 or above is not kept. A request sent again with the same key runs again. Before you send a write again after a 500, check whether it took effect.

Keys are kept per shop and mode, not per API key. If two of your systems sent the same value, the second would get the first one's answer. A new random UUID for each request avoids that.