Introduction

Within our API, the concept of idempotent requests stands as a potent tool, allowing you to reattempt requests without the risk of unintended side effects. Idempotency ensures that executing the same operation multiple times yields the same result as executing it only once. This documentation elucidates how to harness idempotent requests to establish a more reliable and robust interaction with our API.

Using Idempotency Keys

For effectively leveraging idempotency and securely retrying requests, our API provides support for idempotency keys. These keys serve as unique identifiers for requests, enabling the server to recognize repeated requests and deliver consistent responses. By including an Idempotency-Key: <key> header in your request, you indicate that the operation should be treated as idempotent.

How It Works

Our idempotency mechanism captures the outcome of the initial request made using a specific idempotency key, irrespective of its success or failure. Subsequent requests bearing the same key will yield the same outcome, even if that outcome includes error responses such as 500 errors. This guarantees that retries of the same request do not introduce unpredictability.

Generating Idempotency Keys

Generating distinct idempotency keys is crucial to avoiding collisions and upholding the integrity of idempotent actions. While we provide flexibility in generating these keys, we recommend methods like V4 UUIDs or other random strings with ample entropy. Idempotency keys must consist of alphanumeric characters, dashes (-), and underscores (_), with a minimum length of 8 characters and a maximum of 255 characters.

Key Lifecycle and Management

Idempotency keys are automatically eligible for removal from our system after they age at least 24 hours. Attempting to reuse a key after it has been pruned results in a new request, as if the original request had never been made.

Exceptional Cases

Lock is held

Our API employs a locking mechanism to prevent concurrent execution of requests with the same idempotency key. Upon initiation of a request with an idempotency key, the system places a lock on that key to ensure that only one instance of the request can be processed at a time. This mechanism prevents race conditions and maintains data integrity during critical operations. In scenarios where the lock is currently held, a 409 Conflict response will be returned.

Best Practices

POST Requests: All POST requests can leverage idempotency keys to ensure safe retrying of operations.

GET and DELETE Requests: Since GET and DELETE requests are inherently idempotent, including idempotency keys in these requests is unnecessary and should be avoided. Please note: the response codes may differ but the effect (i.e. server state) of sending duplicative requests will remain unchaged.

Example

Below illustrates an example of an idempotent request