What does X-Idempotency-Key refer to?

Consiglio

Last updated on 2026-03-19.

Idempotency ensures that repeated identical requests produce the same result, even if they are retried due to network issues, timeouts, or other temporary issues. This behavior prevents duplicate resource creation or unintended side effects in APIs that accept POST or PATCH requests.

The X-Idempotency-Key HTTP header plays a central role in implementing idempotency. Integrators use this header to uniquely identify requests, enabling the API to track and manage their outcomes across retries.

For additional information, please consult the dedicated Idempotency section in the API documentation.

With the latest API update on March 18, 2026, a new response header, X-Idempotency-Replayed, has been introduced for all POST and PATCH requests. This header allows integrators to clearly distinguish between retried requests ("true") and newly processed requests ("false"), improving transparency and simplifying debugging.

For more details, please refer to our blog article: Unified API Update: Enhanced Idempotency Handling.