---
title: Idempotency
description: Use idempotency keys to retry mutating REST requests safely, replay completed responses, and avoid executing an operation twice.
---

Mutating requests may include an idempotency key:

```http
UDX-Idempotency-Key: <unique-key>
```

The `UDX-Idempotency-Key` header is optional for mutating requests. Omitting the key is allowed, but an unkeyed request has no UDX duplicate or replay protection: the request executes normally, and UDX cannot recognize a retry as a duplicate. The request still uses normal authentication and member rate limits. When you need safe retry and replay behavior, use a UUIDv4 or another high-entropy string up to 255 characters. Generate one key for each operation and reuse it only when retrying that operation.

## Retry the Same Operation

For a request that included an idempotency key, retry with the same method, path, query string, body, and key. UDX returns the original response instead of performing the operation again. Without a key, UDX cannot provide this protection. A replayed response includes:

```http
UDX-Idempotent-Replayed: true
```

Never reuse an idempotency key for a different request. UDX rejects that reuse with HTTP `422 Unprocessable Content` instead of executing the new operation. If an identical request with the same key is still running, UDX rejects the duplicate attempt with HTTP `409 Conflict`; wait, then retry it with the same key.

For a signed request, generate a new timestamp and signature for each attempt. When a request includes an idempotency key, the key is part of the signed message, so the signature must include the same key sent in the request. An unkeyed request is signed without that value. See [Authentication](/authentication#sign-rest-requests).

## Handle Rejected Requests

| Status | Meaning                                                            | What to do                                                                         |
| ------ | ------------------------------------------------------------------ | ---------------------------------------------------------------------------------- |
| `400`  | A supplied idempotency key is empty or invalid.                    | Send a valid key, or omit the header.                                              |
| `409`  | The first request is still running.                                | Wait, then retry with the same key.                                                |
| `409`  | The operation completed, but its response was too large to replay. | Do not send the operation again. Read the affected resource to confirm the result. |
| `422`  | The key was already used for a different request.                  | Use a new key for the new operation.                                               |

The response's `detail` field distinguishes the two `409` cases.

A request rejected by a REST rate limit is not saved as the operation's result. Wait for `Retry-After`, then, if the mutation used a key, retry with that same key and a new timestamp and signature. See [Rate Limits](/rate-limits).