Idempotent requests

To ensure safe retries of requests without unintentional duplicate operations, our API offers idempotency features. If you're working on actions like record creation or updates, the integration of an idempotency key can prove invaluable. This key allows you to re-initiate a request, especially in situations like connectivity disruptions, ensuring no unwanted duplications or repeated updates.

Making an idempotent request

For an idempotent request, include an extra header: X-Idempotency-Key: <key>

Upon receiving a request with a unique idempotency key, our system commits to memory the status code and the body of the response. This holds true irrespective of whether the request was a success or a failure. Any subsequent requests carrying the same key will fetch identical responses, preserving this consistency even in the face of server errors.

What is an idempotency key?

This key is a special marker, generated on the client side, which our server leans on to detect and avert potential repetitions stemming from retried requests. Key aspects include:

• Generation: While the method for generating unique keys rests with you, we accept only UUIDs as idempotency keys. This ensures a low likelihood of overlapping keys.
• Storage Considerations: It's important to note that results are only stored if an API endpoint started processing. Should the incoming parameters fail validation, or if another conflicting request is being processed simultaneously, no idempotent result will be stored. In such scenarios, it's safe to reinitiate these requests.

Idempotency in Different HTTP Methods

• POST: All POST requests must be paired with idempotency keys to ensure safe retries.
• GET & DELETE: Attaching idempotency keys to GET and DELETE requests is unnecessary and should be refrained from, given that these request methods are inherently idempotent.