Idempotency

Some endpoints that create resources (for example the Book Tickets API) require an idempotency key. An idempotency key lets you safely retry the same request without ever creating a duplicate resource. If a network issue, timeout or client crash causes you to re-send the same request, e-guma will return the original response instead of processing it a second time.

Idempotency is required on endpoints where it is documented, and must not be used on endpoints where it is not documented.

How to send the key

Send the Idempotency-Key HTTP header with every request that requires it:

Idempotency-Key: 7f2d9e4b-1c33-4fab-8a42-abcdef123456

Recommendations for choosing a key:

Use a unique value per logical operation attempt (e.g. a UUID version 4).
The key must be a non-empty string.
Generate the key on your side before sending the request and re-use exactly the same value on every retry.
Do not reuse keys across different logical operations (for example, do not use the same key for two different bookings).

How retries behave

When you call an endpoint with an Idempotency-Key:


First request	The request is processed normally and the response is stored against the key.
Retry with the same key and same body	The original response is replayed with the same HTTP status code and the same JSON body. No new resource is created. Replayed responses include the header `Idempotent-Replayed: true` so you can tell them apart from the original response if you need to.
Retry with the same key and a different body	The request is rejected with `422 idempotency_key_reused`. Either generate a new key, or re-send the original body.
Retry while the first request is still being processed	The second request is rejected with `409 idempotency_conflict`. Wait a moment and try again; once the first request finishes, follow-up requests with the same key and body will be replayed.

Scope and expiry

Keys are scoped to the merchant of the API key. You can safely reuse the same key value across merchants.
Keys are also scoped to the endpoint (for example, booking keys and future non-booking keys are independent).
Records are kept for 72 hours after the request completes, then they expire automatically. After the record has expired, the same key may be used again.

When not to rely on idempotency

The idempotency guarantee covers the response of the original request. It does not cover changes that were made to the underlying resource between the original request and the retry (for example, if somebody cancels the booking in between). If you are unsure whether the original request succeeded and the response is no longer available, use the corresponding read endpoint to check the current state of the resource.