Network issues, timeouts, and client retries can cause the same operation to be processed multiple times, leading to data inconsistencies or unintended side effects.

Idempotency keys help manage retries safely, ensuring that each operation is processed only once.

How to use idempotency keys

You can make write API requests (e.g., POST, PUT, PATCH) idempotent by including the Idempotency-Key header in your request (using a uuid format).

The server uses this key to recognize retries of the same request and check the cache for an entry matching the company (client) and idempotency-key.

• If no cache entry exists, the request is processed, and the response is stored in the cache.
• If a cache entry exists, the cached response is returned, including transient (status = 409, 429) and unexpected exceptions (status ≥ 500).

In case of an error, use a new idempotency key for retries.

Note that responses will be cached for 24h.