During a network call, various events like failures and timeouts can occur. In situations such as payouts or anyway sensitive/mission-critical operations, you shouldn't assume that a failed request can be retried safely, as our server might have already processed a payment. To address this concern, you can utilize idempotency keys.

Idempotency keys are uniquely generated values on the client side, which can be included in an HTTP request using the header X-Idempotency-Key. The concept behind idempotency keys is to encourage clients to reuse the same key when re-attempting a request due to unknown or potentially unsafe errors.

When a request is sent to our server with an idempotency key, the server caches the corresponding response for that specific request. If subsequent requests against the same URL use the same idempotency key, the server retrieves the cached response linked to that key, writing that back straight away to the client without re-processing what would otherwise have been a duplicate operation.

🏎️
Races
If a client submits two or more concurrent requests using the same idempotency key, the server will return an error. A race condition occurs if, by the time the first request wins the race, the server has not yet responded (meaning the response is not cached yet), and additional requests are sent before the first request has completely cached and released its state. In such cases, the server will detect the race condition and notify the client with the error code IDEMPOTENCY_RACE (see: Error codes)

⌛
TTL
The cached responses associated with idempotency keys will remain valid for up to 24 hours. After this period, the server reserves the right to purge or remove them from the cache at any time.

🔢
Format
Currently, there is no strict requirement for the format of idempotency key values. However, clients are advised to use identifiers that have a lower likelihood of collisions, such as UUIDv4. Limit to 255 characters.