# Идемпотентность

> Заголовок Idempotency-Key в Slicer API — как повторить POST-запрос после сбоя сети и не запустить монтаж или не списать токены дважды.

Источник: https://docs.slicer.media/api/idempotency/

Сеть иногда обрывается в самый неудобный момент: запрос на монтаж ушёл, а ответ не пришёл. Если просто повторить его, можно запустить второй монтаж и заплатить дважды. Заголовок `Idempotency-Key` решает это: повтор с тем же ключом вернёт ответ первого запроса, а не выполнит операцию снова.

## Как пользоваться

Придумайте ключ на **одну операцию** — проще всего UUID — и отправляйте его во всех попытках этой операции:

Терминал:

```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}'
```

-   Ключ — 8–128 символов из `A–Z`, `a–z`, `0–9`, `_` и `-`. Другой формат — `409 bad_idempotency_key`.
-   Ключ принимают все изменяющие запросы — `POST`, `PUT`, `PATCH`, `DELETE`; запросам `GET` он не нужен.
-   Ключ привязан к токену (у OAuth-приложений — к подключению), методу и пути. Тот же ключ с другим токеном или на другом эндпоинте — это другой запрос.
-   Ключ хранится 24 часа после первого запроса.

## Что вернёт повтор

| Ситуация | Ответ |
| --- | --- |
| Первый запрос завершился успешно | тот же ответ, что и в первый раз, с заголовком `Idempotency-Replayed: true`; операция не выполняется повторно |
| Первый запрос ещё выполняется | `409 request_in_progress` — подождите пару секунд и повторите |
| Первый запрос завершился ошибкой | ключ освобождается: повтор с тем же ключом выполнит запрос заново |

Последнее правило удобно: после `503 ai_unavailable` или `429` можно повторять с тем же ключом, не опасаясь, что ошибка «запомнилась».

> **Осторожно.** Сервер не сравнивает тело повтора с первым запросом. Не используйте один ключ для разных операций — например, для двух проектов из разных файлов: второй получит ответ первого.

## Где это важнее всего

-   `POST /v1/projects`, `…/remount`, `…/retry` — запуск монтажа тратит токены.
-   `POST /v1/projects/{id}/assistant`, `…/translate` — платные правки.
-   `POST /v1/projects/{id}/export` — экспорт с публикацией: повтор без ключа может опубликовать ролик дважды.
-   `POST /v1/uploads`, `POST /v1/uploads/import`, `POST /v1/webhooks` — чтобы не плодить лишние загрузки и вебхуки.

Готовые функции запроса с повторами и одним ключом на все попытки — в разделе [Ошибки](https://docs.slicer.media/api/errors/).

## Что дальше

[ОшибкиКакие ошибки можно повторять.](https://docs.slicer.media/api/errors/)[Монтаж и ценаПодтверждение цены перед запуском.](https://docs.slicer.media/api/montage/)