Skip to main content
Use the optional x-idempotency-key header on requests you send to supported Enfuce endpoints to retry an operation without performing it again after it succeeds. For example, if your connection times out while creating a card, retry the same request with the same key to retrieve the stored response. Check the endpoint reference for the x-idempotency-key header to confirm whether an operation supports idempotency.

​
Send an Idempotency Key

Generate a unique key for each new operation. A Universally Unique Identifier (UUID) is a suitable choice. The key must contain at least one non-whitespace character and must not exceed 64 characters.
Keep the key with your original request and reuse it for retries. Send the same HTTP method, path, query parameters, content type and request body. If you omit the header, the request is processed without idempotency protection.

​
How Retries Work

The key is matched together with the HTTP method and request target, including the path and query parameters. Within that scope, the request payload is compared with the original request. For JSON payloads, changing object property order or insignificant whitespace does not cause a conflict. Array order remains significant. Query parameter names are sorted for matching, but the order of repeated values for the same parameter remains significant.

​
Retention and Failed Requests

The idempotency entry is retained for 24 hours from the start of the original request. Replaying a response does not extend this period.
After the entry expires, a request with the same key is processed as a new operation. Check whether the original operation succeeded before retrying after 24 hours.
Only successful (2xx) responses are stored for replay. If the operation returns an unsuccessful response or raises an error, the entry is removed so a subsequent request with the same key can be processed again. Correct validation errors before retrying.