Idempotency
How the Idempotency-Key header makes retries of Tanitar mutations safe.
Networks fail. If a request times out, you cannot tell whether Tanitar applied it. An
Idempotency-Key lets you retry without applying the change twice: Tanitar remembers the outcome
of the first successful attempt and returns it to every retry.
Which routes require it
Mutating routes that create or move something require the header. Examples include creating a
currency, granting an award, placing a tournament result and reversing a shop order. Calling one without it is
refused with 400 and ACCESS_IDEMPOTENCY_REQUIRED. Each guide notes which routes require it.
On routes that do not require it, the header is ignored. The simplest safe practice is to send a
fresh key on every POST, PUT, PATCH and DELETE.
curl -X POST "$REWARD_API_URL/v1/currencies" \
-H "Authorization: Bearer $TANITAR_API_KEY" \
-H "Idempotency-Key: 0f8d6c1e-5b0a-4c3e-9a57-2e1d7b4f6a90" \
-H "Content-Type: application/json" \
-d '{"currencyKey": "gems", "displayName": "Gems", "scope": "platform", "precision": 0}'Choosing a key
- Generate one key per logical operation, for example a UUID, and store it with the operation before you send the request. Reuse it only to retry that same operation.
- A key is 1 to 256 characters from
A–Z,a–z,0–9,.,_,:and-. Anything else is refused with400andACCESS_IDEMPOTENCY_INVALID. - Keys are scoped to the credential that sends them. Two different API keys never collide, even if they send the same value.
What happens on a retry
Tanitar fingerprints each request from its method, route, path parameters, query parameters and JSON body. Field order in the body does not matter. A retry is compared with the first request under the same key:
| Situation | Result |
|---|---|
| First request with this key | The request runs normally. |
| Same key, same request, first attempt succeeded | The stored status code and response body are returned. Nothing runs again. |
| Same key, same request, first attempt still running | 409 with ACCESS_IDEMPOTENCY_IN_PROGRESS. Wait and retry. |
| Same key, different request | 409 with ACCESS_REPLAYED. The key is already bound to another request; use a new key. |
| Same key, same request, first attempt failed with an error | The request runs again. Failed attempts are not stored, so fixing the cause and retrying with the same key is safe. |
Retention
| Record | Kept for |
|---|---|
| A completed outcome | 24 hours after it completes |
| An in-progress reservation | 60 seconds, so an abandoned attempt never blocks its key for long |
After 24 hours a key is forgotten, and the same key starts a new operation. Retry within that window.
If Tanitar cannot reach the store that holds idempotency records, the request is refused with
503 and ACCESS_STATE_UNAVAILABLE rather than run without protection. Retry it with the same key.
Idempotency and domain keys
Some operations are also deduplicated by the domain itself. For example, an award is recorded
once per trigger, however many times it is requested. That protection lasts beyond the 24-hour
window and across different keys. The Idempotency-Key protects the individual HTTP call. The
guides describe the domain rules where they apply.
Related
- Errors lists every
ACCESS_*code. - Rate limits: a replayed request still counts against your limit.