Idempotent requests

Why it matters

When a connection drops, you cannot tell whether your request reached us. Sending it again could render, and charge, twice. With an Idempotency-Key, the second request gets the first one’s answer back instead, and nothing more is charged.

Create renders is the only endpoint that spends credits, and the only one that takes the header. Reading and cancelling are safe to repeat as they are. Adding a scene is free but not idempotent: sending the same Create a scene twice adds two scenes, so after a dropped connection list your scenes before sending it again.

Send a key

Add the header to the request, and keep it with the work it belongs to so a retry can send it again:

curl -X POST https://www.skipshoot.com/api/v1/renders \
  -H "Authorization: Bearer $SKIPSHOOT_SECRET_KEY" \
  -H "Idempotency-Key: catalog-sync-2026-10-21-sku-NW-VEL-104" \
  -H "Content-Type: application/json" \
  -d '{
  "scene_id": 812,
  "product_id": 4410
}'

Choose a key

• Use a value that names the work, not the attempt: the same job sent again must carry the same key. A UUID you store with the job, or an id from your own system, both work.
• A key is 1 to 255 visible ASCII characters, with no spaces. Anything else is refused with 400 invalid_request.
• Keys belong to your workspace. Two of your keys, or two of your servers, sending the same Idempotency-Key are treated as the same request.

What happens on a retry

Refusals free the key

A request refused before anything was charged, because the workspace has too few credits or a render in it cannot be done, does not hold on to its key. Fix the problem and send the request again with the same key and the corrected body.

Very rarely, a request is interrupted while it is being charged. Its key then answers 409 and asks you to contact us, rather than risk charging you twice. Email admin@skipshoot.com with the key and we will sort it out.

Rules

• A key is remembered for 24 hours, then may be used again.
• The answer replayed is the one first given. If you need a render’s current status, fetch it with Retrieve a render.
• Requests without the header are not deduplicated at all.