Idempotency

Idempotency ensures that multiple identical requests to an API endpoint produce the same result as a single request, regardless of how many times the request is made. This property is essential for preventing duplicate transactions, especially in cases of network failures or other issues that might cause a client to retry a request.

All endpoints using the GET method are inherently idempotent, meaning that repeated retrieval requests for a product or voucher will provide the same response, as long as there are no changes to the underlying data.

Idempotency for transactional endpoints

Currently, the only feature supported by a transactional POST method endpoint is voucher issuance.

To prevent the accidental issuance of duplicate vouchers from repeated requests, an idempotency mechanism using the Idempotency-Key request header is implemented. This key distinguishes repeated requests from new ones.

The idempotency key is a mandatory header to perform voucher issuances.

Generating an idempotency key

The idempotency key must be a unique identifier in the UUID version 4 (random) (opens new window) format. Clients are required to generate a new UUID for each issuance request and store it along with the request parameters for potential recovery.

Using a standard library that supports UUIDv4 to generate this key is recommended.

Important

Generate a new idempotency key for each issuance request. Reuse keys only when attempting to recover from an error.

Note

Retrying a request with an idempotency key is always safe. If the key matches a previous request, no new transaction will occur unless the API never received the initial request.

When to attempt recovery using idempotency?

Attempt recovery if a voucher issuance request fails to receive a response (either successful or error), such as after a timeout or disconnection.

If there's a failure on the client's side, recovery can also be attempted if the idempotency key and other request parameters were stored.

Important

It is the client's responsibility to implement effective error recovery using idempotency. All issued vouchers in production will be invoiced.

Idempotent recovery

Recovery can be manual or automated depending on the situation:

• Automated recovery: Initiate automated recovery either immediately after receiving an API error response or no sooner than 25 seconds after the initial request if no response has been received by setting the allowed timeout. This delay ensures that any potential error in the API or third-party systems are resolved.
• Manual recovery: This can be attempted at any time within 1 month in the production environment, as this is the duration for which records are maintained in the API's idempotent store.

Important

Automated recovery is required for all integrations. However, in cases of failure within a client's system, manual recovery may be the only option.

The auth token used in a retry does not need to be the same as in the original request but it must be valid.

The API verifies the client ID of the auth token, the request path, and the Idempotency-Key against its store to validate a recovery attempt.

Identify recovered responses

Responses retrieved from the API's idempotency store include a Idempotency-Record header set to true. This allows clients to distinguish between new issuances and successful retries.

If the initial request was never received by the API, it is possible for an idempotent response not to have this header.