Idempotency
Retry a write without doing it twice.
Every write under /api/v1 (POST, PUT, PATCH and DELETE) requires an
Idempotency-Key header: a token you choose, 64 characters at most. A missing, blank or too long key is
400 INVALID_INPUT, refused before anything is written.
curl -X POST https://api.shyni.io/api/v1/orders \
-H "Authorization: Bearer $SHYNI_KEY" \
-H "Idempotency-Key: crm-4411-booking" \
-H "Content-Type: application/json" \
-d '{...}'The key is unique per studio, so rotating your API key never lets a retry issue a second voucher or a second refund. The stored answer, though, is replayed only to the API key that made the first request.
What a repeat does
A repeated request under the same key replays the first answer, byte for byte, instead of running the write again.
| Situation | Response |
|---|---|
| Same key, same body, an answer is stored | That status and body, replayed as-is |
| Same key, same body, the first request is still running | 409 IDEMPOTENCY_IN_PROGRESS: retry shortly |
| Same key, a different body | 422 IDEMPOTENCY_KEY_MISMATCH: use a new key |
| Same key, same body, but another API key of your studio | 422 IDEMPOTENCY_KEY_MISMATCH: nothing is run or replayed; use a new key |
A claimed key stays replayable for 24 hours. After that it can be reused to start a fresh request.
In practice
- Generate one key per intended action, for example a UUID or your own order id,
and keep it with the action. Retry network errors and
5xxwith the same key. - A new action gets a new key. A refund is a different request from the issue it refers to, so it needs its own key.
- A replayed key uses no booking rate-limit budget on
POST /orders.
Related: Errors, Rate limits and quota.