Skip to content
SecurityRUOpen Slicer

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.

On this page

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
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 succeededthe same response as the first time, with the Idempotency-Replayed: true header; the operation doesn't run again
The first request is still running409 request_in_progress — wait a couple of seconds and retry
The first request failedthe 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".

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.

What's next

ErrorsWhich errors are safe to retry.Montage and pricingConfirming the price before starting.