# Idempotency

Idempotency ensures that a request can be repeated without unintended side effects.
When an idempotent operation is executed multiple times with the same request parameters, the resulting state of
the resource remains the same as if the request had been executed only once.

This is particularly important in cases where network failures, timeouts, or client-side retries may trigger duplicate
requests.

Several HTTP methods, such as `GET`, `PUT` and `DELETE`, are idempotent by definition.
`POST` and `PATCH` are not guaranteed to be idempotent.

The Transact API optionally provides idempotency guarantees for these methods through the use of **idempotency keys**.
To perform an idempotent request, you may provide an `Idempotency-Key` header with a unique identifier for the request.
If a duplicate request is received with the same `Idempotency-Key`, the operation will not be performed again, and you
will receive the response from the original request.

While the API does not enforce a particular structure for idempotency keys, it is recommended to use a high-entropy
random string (e.g. UUID Version 4) to avoid collisions.

## How it works

- The first request with an `Idempotency-Key` is processed normally.
- Subsequent requests with the same `Idempotency-Key` and identical payload return the previously generated response.
  - A `409 Conflict` response will be returned if another request with the same `Idempotency-Key` is received while the
    first request is still in progress. It is safe to retry this request at a later time.
- Requests using the same `Idempotency-Key` with a different payload will be rejected with a `422 Unprocessable Entity`
  response.
- Idempotency keys expire after 24 hours. Once expired, any request using the same key is processed as a new request.

## Response Headers

When a repeated request returns the original response, it will include the following additional headers:

| Header                | Description                                        |
| --------------------- | -------------------------------------------------- |
| `Idempotent-Replayed` | `true` for a previously generated response.        |
| `Original-Request-Id` | Includes the `Request-Id` of the original request. |