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

# Idempotency

> Ensure safe retries and prevent duplicates using the Idempotency-Key header.

We support **idempotent requests** so that you can retry safely without duplicates. This is important for actions that **create resources**, **upload files**, or **modify data**. For these actions, repeated requests can cause unwanted side effects.

## The definition of idempotency

With idempotency, the **same request, sent many times**, has the **same effect** as one request.

If your client gets a timeout or a network error, retry the request with the **same idempotency key**. We process the request only **once**.

## The operation of idempotency

To make an idempotent request, include a unique key in the header:

`Idempotency-Key: your-unique-idempotency-key`

We store the **status code and response body** of the first request for that key. Each subsequent request with the same key:

* Returns the **original result**, for success or for failure
* Prevents **duplicate processing** of resource creation or updates
* Keeps **data integrity** across retries

This behavior applies also if the first request caused a `500` or other server error. This keeps the result consistent for all outcomes.

<Note>The API ignores the `Idempotency-Key` in `GET` or `DELETE` requests.</Note>

## Key Expiration

* We store idempotency keys for **24 hours**.
* After expiration, the API treats the same key as a **new request**.
* Keys can be **up to 255 characters long**.

## Response Headers

When you use an `Idempotency-Key`, we include these response headers. They help clients see how we processed the request:

| Header               | Description                                                                                                                                |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `Idempotency-Key`    | Shows the key from the request. This confirms that the API accepted and applied the key                                                    |
| `Idempotency-Status` | Shows how we processed the request: `new`: the first execution of the key, `replayed`: a cached response from an earlier identical request |

Example:

```
HTTP/1.1 200 OK
Idempotency-Key: 6aa2f8a3-4ef4-4899-8234-d45a93d1f191
Idempotency-Status: replayed
```

These headers help you debug retries. They show if the API replayed the result or generated a new one.

## Best Practices

* Use a **UUIDv4** or another random, high-entropy string to generate keys.
* **Use a key again** only when you retry the **same exact request**.
* **Do not use the same key** for different operations, endpoints, or payloads.

<Note>Prem API rejects a repeat request with the same key if the **parameters differ** from the original. This prevents accidental misuse.</Note>

## When to Use Idempotency

Use idempotency for each request where duplication has negative effects. Use it when you:

* Upload encrypted files
* Create or modify resources with the API
* Send webhooks or external callbacks
* Start long-running or asynchronous tasks

## Summary

| Header            | Required                                                         | Description                                                                      |
| ----------------- | ---------------------------------------------------------------- | -------------------------------------------------------------------------------- |
| `Idempotency-Key` | Optional (but recommended for all `POST`/`PUT`/`PATCH` requests) | Makes sure that the API performs a given operation only once, also after retries |

The idempotency layer of Prem API **does not cache invalid requests**. If a request fails validation, or if we reject it before execution, we do not store the key. You can retry those requests.

If you need help with implementation or with debugging, contact [support@premai.io](mailto:support@premai.io). Include your request payload and your idempotency key.