Re-run a Format on purpose: version the Idempotency-Key
How Sume Format idempotency works, why a fresh uuid per request defeats it, and how an order id plus a version number gives safe retries and deliberate re-runs.
To re-run a Sume Format on purpose, keep the order id in the Idempotency-Key and bump a version suffix, for example order-8823-lc-v2. To retry safely after a timeout, send the same key and the same body, and Sume returns the original run with idempotency_hit: true instead of starting and charging a second one.
The rules are on the Create a run page. This post turns them into a key scheme and covers the two 409 codes that look alike.
What each replay returns
Send Idempotency-Key on every create. The docs say to derive it from the item the run makes (your order id plus a version you bump only for a re-run), not from the time of the request. A key is up to 255 characters, and its scope is one Format, so the same key sent to two Formats starts two runs.
| What you send | Result | Is a run charged? |
|---|---|---|
| Same key, same body | 200, original receipt, idempotency_hit: true | No second run, no second charge |
| Same key, different body (even a different instruction or attachment list) | 409 idempotency_conflict; nothing runs | No |
| Same key, two requests at once | One wins; the other gets 409 idempotency_key_in_use, retryable | Only the winner runs |
| Same key after a failed create (402, 503) | Key was released; retry with the same key | Only if the retry succeeds |
Retry versus re-run
A retry means you do not know whether the first call landed. Repeat the exact key and body. A re-run means you want a new result for the same order, such as a different take. Bump the version, which changes the key, and you may change the body freely.
The failure mode is a random key per request. The docs state it plainly: if you use a new uuidgen each time, the header has no effect, so a client retry after a timeout can start a second run. The other failure mode is editing the body and keeping the key, which returns 409 idempotency_conflict and runs nothing.
Failed runs are different
A key that already produced a run stays tied to that run, even if the run later failed. Replaying it returns the failed receipt rather than trying again. After a failed run, either continue it with previous_run_id or send a new version of the key. The retry table in the safe-retry post shows which codes call for which.
503 studio_agent_upstream_unavailable at create is a Sume-side outage, and the docs say to retry with the same key, since no run was created.
A key scheme that survives audits
Keep the scheme boring and written down.
- Format:
<system>-<order id>-<format short name>-v<n>, well under 255 characters. - Store the key with your order row before the HTTP call, so a crashed worker reuses it.
- Treat
idempotency_hit: trueas success and store the returned run id. - Bump
nonly through a deliberate action, such as a button labelled re-run, never in retry code. - For a bulk queue, remember that replaying a spent key returns the old queue with
202instead of a new one.
Sources
Related posts
More in Formats
- Sume Format instruction limit: why long briefs belong in input
A Format instruction accepts 8000 characters but only about the first 4000 reach the prompt. Put long briefs in the input field, which is stored whole as data.
- Sume Format run image attachments: 30 images, 30 MB, 500 MB
A Sume Format run takes up to 30 images, 30 MB each and 500 MB per run, in JPEG, PNG, WebP, GIF, or AVIF. Here is what invalid_attachment means.
- Does your Format webhook receiver pass OWASP's checklist?
Check a Sume Format webhook receiver against OWASP's webhook cheat sheet: raw body, HMAC, five-minute window, dedupe on request_id, and where docs are silent.
- Which Format version ran my API call? Check the receipt
Every Sume Format run receipt carries format.version. Read it after you edit a package, so a bulk batch or schedule is never judged against the wrong version.
Written by Sume