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: