Retry a failed run: same idempotency key returns old failure

To retry a failed Sume Format run, send the create again with a new Idempotency-Key. The old key is bound to the receipt you already hold, so reusing it points back at the run that failed. When the failure left clips behind, continue the run with previous_run_id instead of starting over.

Why does the same key not retry?

Two different failures are easy to confuse. A failed create, such as a 402 or 503, means nothing ran and nothing was charged, and the key is released, so the same key is fine after you fix the cause. A failed run is different: the create succeeded, you hold a receipt with status: "failed", and the key belongs to that receipt. A run failure is never a later create error; once you hold a receipt, failures arrive on it.

Which failures should I retry, and how?

Codes from the run-failure table, read 2026-09-29.

When should I continue instead of retrying?

A failed run can leave real work behind: artifacts[] still lists everything the run generated. Send previous_run_id on a new create and the next turn continues the same conversation, so the agent can redo one part and leave the rest alone. A failed run that left work behind can be continued; one that left nothing cannot, and returns 400 previous_run_not_resumable.

A continuation is a new run with a new id, its own spend cap and its own key, so give it a fresh Idempotency-Key too. Bind the same output_schema on every turn, since it is per run, not inherited.

How do I know the run really failed?

Read status on the receipt. On failure primary_output_url is null, so if (run.primary_output_url) is a safe test for whether the deliverable exists. Treat the code set as open and fall through on codes you do not know. More in the Format errors page.

What is the safest retry sequence?

Read the failed receipt first. Check error.code and artifacts[]. If the code is one the table above marks as retryable and artifacts[] is empty, mint a new key and create again. If clips are on the thread, continue the run so they are not regenerated.

Derive the new key from the same thing being made plus a bumped version, for example the order id with a retry counter, so a network retry of your retry still replays instead of starting a third run.

Set a fresh spend cap on the new run. It is its own run, and a run can never spend past its own effective cap.