Sume Format run idempotency key: order id plus version, not uuidgen
Derive the Sume Format run Idempotency-Key from your order id plus a version. A fresh uuidgen per request makes the header do nothing and double-bills retries.
Derive the Idempotency-Key for a Sume Format run from the thing the run makes, such as your order id plus a version: order-8823-lc-v1. A new uuidgen on every request means the header has no effect, so a retried create starts a second run and a second bill. With a stable key, the same body returns a 200 replay of the first run, where a fresh create returns 202. Source: Create a Format run, read 2026-10-06.
What happens on each retry?
Sume compares the key and the body.
| Request | Result |
|---|---|
| Same key, same body | 200, replay of the original run |
| Same key, different body | 409 idempotency_conflict |
| Concurrent duplicate | 409 idempotency_key_in_use |
| New key | 202, a new run |
How do I handle a real change?
Bump the version in the key. If the order changes, order-8823-lc-v2 is a different request on purpose, and it can reference the earlier run with previous_run_id. Keep the key to ASCII and stable across your own retries.
Sources
Related posts
More in Formats
- List Sume Format runs: cursor pages, newest first, one Format only
Sume lists Format runs per Format, newest first, limit 1 to 100 and a next_cursor. There is no cross-Format list, so keep your own index of run ids.
- Format run output_extraction_failed: it stays completed, read again
output_extraction_failed is a transport failure, not a verdict. The run stays completed and Sume projects the output again on your next read of the receipt.
- Format run failed primary_not_deliverable: audio under a video key
A Format that makes video fails with agent_reported_failure and primary_not_deliverable when the primary output is audio or a still. How to read and fix it.
- Format run scene status stand-in vs failed: which scenes to retry
Give each scene a status of succeeded, stand-in or failed, then retry only the bad ones with previous_run_id. The schema, the receipt rule and the call.
Written by Sume