# Idempotency

> The Idempotency-Key header in the Slicer API — how to repeat a POST request after a network failure without starting a montage or charging tokens twice.

Source: https://docs.slicer.media/en/api/idempotency/

Networks fail at the worst moment: the montage request went out, but the response never came back. Simply repeating it might start a second montage and charge you twice. The `Idempotency-Key` header solves this: a retry with the same key returns the first request's response instead of running the operation again.

## How to use it

Make up a key for **one operation** — a UUID is easiest — and send it with every attempt of that operation:

Terminal:

```bash
KEY=$(uuidgen)

curl https://api.slicer.media/v1/projects \
  -H "Authorization: Bearer $SLICER_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $KEY" \
  -d '{"uploadIds":["7d0c6a4e-2f7b-4f5e-9a0e-3b8f2c1d9e61"],"confirmCost":24}'
```

-   A key is 8–128 characters from `A–Z`, `a–z`, `0–9`, `_` and `-`. Any other format gets `409 bad_idempotency_key`.
-   The key is accepted by every modifying request — `POST`, `PUT`, `PATCH`, `DELETE`; `GET` requests don't need it.
-   The key is bound to the token (for OAuth apps — to the connection), the method and the path. The same key with another token or on another endpoint is a different request.
-   A key is kept for 24 hours after the first request.

## What a retry returns

| Situation | Response |
| --- | --- |
| The first request succeeded | the same response as the first time, with the `Idempotency-Replayed: true` header; the operation doesn't run again |
| The first request is still running | `409 request_in_progress` — wait a couple of seconds and retry |
| The first request failed | the key is released: a retry with the same key runs the request again |

The last rule is handy: after `503 ai_unavailable` or `429` you can retry with the same key without worrying that the error was "remembered".

> **Caution.** The server doesn't compare a retry's body with the first request. Don't reuse a key for different operations — for example, for two projects from different files: the second one would get the first one's response.

## Where it matters most

-   `POST /v1/projects`, `…/remount`, `…/retry` — starting a montage spends tokens.
-   `POST /v1/projects/{id}/assistant`, `…/translate` — paid edits.
-   `POST /v1/projects/{id}/export` — export with publishing: a retry without a key could publish the video twice.
-   `POST /v1/uploads`, `POST /v1/uploads/import`, `POST /v1/webhooks` — to avoid extra uploads and webhooks.

Ready-made request functions with retries and one key for all attempts are in [Errors](https://docs.slicer.media/en/api/errors/).

## What's next

[ErrorsWhich errors are safe to retry.](https://docs.slicer.media/en/api/errors/)[Montage and pricingConfirming the price before starting.](https://docs.slicer.media/en/api/montage/)