What is idempotency?

Idempotency is a property of an API operation where making the same request multiple times has the same effect as making it once. Regardless of how frequently an idempotent API request is repeated, the resulting state or outcome remains the same as if executed only once.

Idempotency is crucial when dealing with unreliable network connections, retry mechanisms, or when multiple clients may send duplicate requests. By designing idempotent APIs, developers can ensure that repeating a request won't lead to unintentional side effects or inconsistencies in the system.

Implementing idempotency involves assigning a unique identifier or token to each API request and using it to track and trace duplicate requests. The server can check this identifier and respond accordingly, ensuring that only the first occurrence of the request has any effect, while subsequent duplicate requests are ignored or produce the same response.

How to perform an idempotent request?

Send the request with the HTTP header X-GCS-Idempotence-Key. All requests with the same key will be considered attempts for the same request. It's important that you use unique keys, for example, UUIDs. These keys are stored for a period of 24 hours. If a second attempt is sent with the same key, there are two possible outcomes:

• if the first request has finished, the same response is sent, however, some information in this response may be updated: for example, the current status of a payment
• if the first request has not finished yet, a response with HTTP response code 409 (Conflict) is sent instead; you should be prepared to handle this case

To distinguish the first attempt from subsequent attempts with the same key, responses for all subsequent requests all include HTTP header X-GCS-Idempotence-Request-Timestamp, with as its value the timestamp of the first request, as the number of milliseconds since January 1st, 1970 00:00:00 UTC.

Depending on the used API, there are various idempotent request handling guidelines available for the following methods:

Server API

• Create payment
• Create refund
• Create payout
• Create dispute 

File Service API

• Upload file