Перейти к содержанию
БезопасностьENОткрыть Slicer

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

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

На этой странице

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

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

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

Терминал
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 — чтобы не плодить лишние загрузки и вебхуки.

Готовые функции запроса с повторами и одним ключом на все попытки — в разделе Ошибки.

Что дальше

ОшибкиКакие ошибки можно повторять.Монтаж и ценаПодтверждение цены перед запуском.