API Reference

Idempotent Requests

Ensure that your same requests are executed only once.

Overview

The APIs support idempotency, ensuring that retrying requests can be done safely without accidentally performing the same operation more than once. By using an idempotency key, you can safely repeat a request if a connection error occurs, without risking the creation of duplicate objects or performing updates multiple times.


How Idempotency Works

To perform an idempotent request, include an additional x-idempotency-key element in the request header.

Key Management

  • Generation: The client generates a unique idempotency key using a UUID.
  • Life Cycle: The system automatically removes the key 24 hours after it is created.

When a request is made with an idempotency key which is validated by UUID format, the resulting status code and body of the first request associated with that key will be saved, regardless of whether the request succeeds or fails. Any subsequent requests with the same key will return the same result, including any errors.


Handling Requests

Idempotency results are saved only after an endpoint begins execution. If incoming parameters fail validation, if the request conflicts with another concurrent request, or for network issues preventing the initiation of an API endpoint execution, the idempotent result will not be saved. In these cases, you can safely retry the request.