Format run Idempotency-Key: header or body, and four replay outcomes
Send Idempotency-Key as a header or idempotency_key in the body; the header wins. Same key and body gives 200 idempotency_hit true; a new body is a 409.
On a Sume Format run you can send the idempotency key as the Idempotency-Key header or as idempotency_key in the JSON body, and when you send both, the header wins. The same key with the same body returns the original run with 200 and idempotency_hit: true, and nothing is charged twice.
The Format API documents four distinct outcomes for a repeated key, and each needs different client code.
Four outcomes for one key
This is the idempotency table from the Create a run page, with the recommended action added (read 2026-10-03).
| Situation | Result | Client action |
|---|---|---|
| Same key, same body | 200 with the original receipt and idempotency_hit true | Use the receipt; do not start a second poll loop |
| Same key, different body (even a different instruction or attachment list) | 409 idempotency_conflict; nothing runs | Your key derivation is unstable; derive it from the intent, not a timestamp |
| Same key, two requests at once | One wins; the other gets 409 idempotency_key_in_use (retryable) | Wait about a second and resend to receive the original run |
| Same key after a create that failed (402, 503) | The key was released | Fix the cause and retry with the same key |
Scope and size
Keys are scoped to one Format: the same key sent to two Formats starts two runs. A key can be up to 255 characters, so hash long business keys instead of truncating them.
A fresh run answers 202, and a replay answers 200, so check the idempotency_hit field or the status code before you schedule polling. Both carry the full receipt with data.id and the URLs to follow.
curl -sS -X POST "https://api.sume.com/v1/formats/acme/live-commerce/runs" \
-H "Authorization: Bearer $SUME_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: order-8823-lc-v1" \
-d '{"input":{"order_id":"8823"}}'A comparison to the IETF draft
The expired IETF draft on the Idempotency-Key header (read 2026-10-03) says a missing key is a 400, a reused key with a different payload is a 422 and a concurrent duplicate is a 409. Sume uses 409 for the changed-payload case, as idempotency_conflict, so do not branch on 422 for it. See the draft comparison for more.
Sources
Related posts
More in Formats
- Format run media budget: 30 files, 10 videos, 10 audio for a lookbook
A Sume Format run shares one attachment budget: 30 files, 30 images, 10 videos, 10 audio. Plan a lookbook run so it stays under invalid_attachment.
- Format run media URLs are public: copy on webhook or proxy
Sume Format run media lives at durable public media.sume.com URLs. If customer A must not see customer B's video, copy it at receipt time or proxy it.
- Format run `model` picks the orchestrator, not the video model
A new image or video model launches and you set model on a Sume Format run. That field picks the orchestrating LLM only; media models come from Format tools.
- Format run structured output: output_schema or response_format
Pass one JSON Schema as output_schema or response_format on a Format run. Sending both is a 400, and a schema-valid run can still fail with output_error.
Written by Sume