Idempotency key replay returns the original response: read the flag
Replaying an Idempotency-Key on a Sume run create returns the original receipt with idempotency_hit true. How to spot a replay, and what a new body does.
On a Sume run create, sending the same Idempotency-Key with the same payload returns the original receipt, not a new run, and the receipt carries idempotency_hit: true. Check that field before you treat a response as fresh work, because a replay starts nothing and charges nothing.
How do I tell a replay from a new run?
For Format runs, two status codes mean success: 202 is a fresh run, and 200 is an idempotent replay that returns the original run. Both carry the full receipt, so store data.id and follow the URLs on it either way. The idempotency_hit field is true when a receipt is a replay rather than a new run.
Agent Completions behave the same way: replaying a key returns the original receipt with idempotency_hit: true.
What happens on each kind of replay?
The Format-run table from the docs, in short form.
| Replay | Result |
|---|---|
| Same key, same body | 200 with the original receipt and idempotency_hit: true. No second run, no second charge. |
| Same key, different body | 409 idempotency_conflict. Nothing runs. |
| Same key, two requests at the same moment | One wins; the other gets 409 idempotency_key_in_use, which is retryable. |
How should I build the key?
Derive it from the thing being made, such as your order id plus a version you bump when you deliberately want a re-run, not from the moment of asking. A random uuidgen per request makes the header decorative, because a retry never repeats it. Keys are scoped to one Format: the same key sent to two Formats starts two runs.
Does a replay give me the result?
It gives you the original receipt, and that run may still be going or may have finished. Poll its status URL as you would for a new run. If that run fails, its key stays bound to the receipt you already hold; see failed run retry needs a new key. For the changed-body case, read conflict vs key in use. Full tables are in Call a Format.
What should my client do with idempotency_hit?
Branch on it only for bookkeeping. If it is false, you started a run, so record the id and its spend cap. If it is true, you already had that run: skip the second record, because no second run and no second charge occurred.
Keep the replay path boring. The receipt has the same shape either way, with status, result and cancel URLs, so one code path can poll a run whether it came from a fresh 202 or a replayed 200.
A 409 idempotency_conflict is the opposite signal: the key was already used with a different body. Fix your key derivation instead of retrying as is.
Sources
Related posts
More in Developers
- Ideogram character reference API: what Sume passes through
Ideogram's API has character reference. Sume lists ideogram/ideogram-v3 with input_references, low, medium, high quality; no character reference is documented.
- Ideogram V3 Turbo, Balanced, Quality: how Sume maps them
On Sume the quality field takes low, medium or high for Ideogram V3, and those map to TURBO, BALANCED and QUALITY. Omit it and BALANCED runs. Price is flat.
- Image API provider.only and provider.order: which slug works?
Sume's image API takes provider.only and provider.order but lists one endpoint per model, slug sume. Which routing fields do anything, and the 400 for the rest.
- Image generation API streaming: partial images on Sume
Sume's image API does not stream partial images yet: stream true returns 400 streaming_not_supported. Submit async, read events, or use a webhook.
Written by Sume