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 and an identical request body, 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.
Request body mismatchAn idempotency key is tied to the exact raw bytes of the request body it was first sent with. If the same key is reused with a request body that differs in any way, the server rejects the request with the error code
IDEMPOTENCY_KEY_BODY_MISMATCH(see: Error codes) and does not process it. The comparison is byte-for-byte, so bodies that are semantically equivalent but serialised differently (e.g. JSON properties in a different order, different whitespace or indentation, a trailing newline) are rejected as well. When retrying, resend the original request bytes unchanged; do not re-serialise, reformat or reorder the body. A different request must always use a new idempotency key.
RacesIf 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)
TTLThe 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.
FormatCurrently, 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.
