Idempotency and retries

A request can fail after Shootika has done the work: the connection drops before the answer arrives. Retrying a shoot blindly could then start, and pay for, a second frame. The Idempotency-Key header makes a retry safe.

Send an Idempotency-Key

Every POST accepts an Idempotency-Key header: a unique string you choose, 1 to 255 characters, for this one request. A UUID works well.

Make the key once per job, before the first attempt, and store it with the job:

SHOOT_KEY=$(uuidgen)

Then send it:

curl https://api.shootika.com/v1/frames \
  -H "Authorization: Bearer $SHOOTIKA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $SHOOT_KEY" \
  -d "{\"product_id\": \"$PRODUCT_ID\", \"source_image_id\": \"$IMAGE_ID\", \"scene_id\": \"$SCENE_ID\"}"

On a retry, send the same request again with the same key. Do not make a new key: a new key on a retry is a new request, and for POST /v1/frames a second shoot that uses a second frame.

Keys belong to your store, not to one API key. Two systems that call the API for the same store share one set of Idempotency-Key values, so make them unique across all of them (a UUID is).

The endpoints that take it are POST /v1/products, POST /v1/products/{product_id}/images, POST /v1/scenes, POST /v1/frames and POST /v1/frames/{frame_id}/approval. Always send one on POST /v1/frames, which uses a frame.

What happens on a retry

You send	Shootika answers
The same key and the same request, after a 2xx	The first answer again, for 24 hours. The work is not done twice.
The same key and the same request, after anything else	The request runs again. Only 2xx answers are stored.
The same key while the first request is still running	409 idempotency_in_progress. Wait and retry with the same key.
The same key with a different request	409 idempotency_conflict.

“The same request” means the same method, address and body. A first request that was abandoned holds its key for at most 5 minutes; after that the key can be used again.

Which errors to retry

Answer	Retry?
A network error or timeout	Yes, with the same Idempotency-Key.
429 rate_limited	Yes, after the number of seconds in the Retry-After header.
503 service_busy	Yes, in a moment. When the answer has a Retry-After header, wait that long.
503 upload_failed	Yes, in a moment. The photo could not be stored.
500 internal_error	Yes.
409 idempotency_in_progress	Yes, with the same key, once the first request has had time to finish.
409 media_processing_failed	Yes.
Other 4xx	No. The request needs a change first: read the code.

A failed frame is not a failed request: the shoot was accepted and the frame did not come out. It is refunded. To try again, start a new shoot with regenerate_of, under a new Idempotency-Key. See Frames.