> ## Documentation Index
> Fetch the complete documentation index at: https://nextgen-docs.enfuce.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Idempotency support

> Retry supported API requests without repeating a successful operation.

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.

```http theme={null}
x-idempotency-key: 97af06e7-413a-49d6-8f28-0f6c9c80d21b
```

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.

| Request | Behaviour |
| :- | :- |
| First request with a new key | The operation is processed and its successful response is stored. |
| Same key and matching payload after success | The stored HTTP status and response body are returned without repeating the operation. |
| Same key with a different payload | You receive `409 Conflict`. A mismatched payload always means a conflict. Generate a new key if you intend to perform a distinct operation. |
| Matching request while the original is still processing | The request waits up to five seconds for completion. The stored response is returned if it becomes available. Otherwise, you receive `409 Conflict`; wait before retrying with the same key and payload. |
| Blank or whitespace-only key, or key longer than 64 characters | You receive `400 Bad 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.

```mermaid theme={null}
sequenceDiagram
    participant You as Your Application
    participant Enfuce
    You->>Enfuce: Request with a new x-idempotency-key
    Enfuce->>Enfuce: Perform operation and store successful response
    Enfuce-->>You: Successful response
    Note over You: Retry after a timeout or lost response
    You->>Enfuce: Same key and matching request
    Enfuce-->>You: Stored response without repeating the operation
```

## 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.

> [!WARNING]
>
> 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.