Our API supports idempotent operations for select POST, PATCH, and DELETE endpoints via the Idempotency-Key HTTP header. This mechanism helps prevent duplicate resource creation or modification when retrying requests due to network interruptions or timeouts.

Use of the Idempotency-Key is not required, but highly recommended.

📘

Review API Guide for Supported Endpoints

Not all endpoints support idempotency. Please refer to our API Guide for the full list of endpoints where idempotency is currently implemented.

How It Works

Idempotent Behavior:

When a request is made with an Idempotency-Key, we check if a successful request with the same key has already been processed in the past 24 hours:

• If so, we return the original response, even if the underlying resource has since changed due to other operations.
• If the key is new or expired, the request is processed normally.

Time-to-Live (TTL):

Each idempotency key is valid for 24 hours from the time of the initial request.

How to Use It

Include the Idempotency-Key in your request headers:

idempotency-key: your-unique-idempotency-key-here 

Best Practices

Generate a unique key using a UUID/GUID

To ensure reliable deduplication across retries, generate a UUID (e.g., uuidv4) on the first request attempt and reuse the same key for any retries of that operation.
Example (pseudo-code):

// Example using uuid
  const { v4: uuidv4 } = require('uuid');
  const idempotencyKey = uuidv4();
  headers['idempotency-key'] = idempotencyKey;

Store the key per operation attempt

If your client retries a request (due to timeout, disconnection, etc.), reuse the same key to avoid duplicating the operation.

Don’t reuse keys across different endpoints or request types:

Reusing keys across unrelated operations can lead to stale or misleading responses.

Always send the key on the first attempt:

Don’t wait for a retry to include the key. Doing so ensures full traceability and consistent behavior from the first request onward.