# Idempotent requests

Knock supports idempotency so that requests can be retried safely without unintended side effects.

To perform an idempotent request, set an `Idempotency-Key` header on your request. This idempotency key is a unique string of up to 255 characters that you generate for each request. It is used to identify and prevent the duplicate processing of requests. If you retry a request with the same idempotency key within 24 hours from the original request, Knock will return the same response as the original request. Idempotent requests are expected to be identical. To prevent accidental misuse, Knock returns an error when incoming parameters don't match those from the original request.

Idempotency is currently supported on a limited set of endpoints. Today, only `POST /workflows/:key/trigger` accepts the `Idempotency-Key` header; sending it on any other endpoint has no effect.

Idempotency keys can be random UUIDs, or they can have some meaning in your application. For example, if you are sending a notification after a user has placed an order, you could use a key that is a combination of the reason for the notification, the user ID, and the order ID (e.g. `order-placed:user-123:order-456`). If your user then cancels the order, you could use an idempotency key like `order-cancelled:user-123:order-456`. This will ensure each type of notification is only sent once, even if your system retries the request multiple times.

If you are making calls to Knock from a job queue, the ID of the job can be a good choice for an idempotency key. If the job fails and is retried, the same idempotency key will be used.

When a request is replayed from the idempotency cache, the response includes two headers:

1. An `original-x-request-id` header pointing to the `x-request-id` of the original request.
2. An `idempotent-replayed: true` header so you can tell the response was cached.

Knock only caches successful responses (`2xx`). Requests that return a `4xx` or `5xx` response are not stored, so retrying with the same idempotency key after a failure will execute the request again rather than replaying the previous response.

> **The default idempotency window for the Knock API is 24 hours.** support@knock.app.

```text title="Response headers (on cache hit)"
original-x-request-id: F1FIj5XwD_m4h0sAASfi
idempotent-replayed: true
```