Which failed Format runs can you retry without paying twice?

A failed Format run is safe to retry without paying for finished clips again when the docs say the clips stay on the thread: provider_unavailable, incomplete_assembly, agent_reported_failure and output_extraction_failed with harvest_threw. For those, continue the run with previous_run_id or retry with a new Idempotency-Key, and read the error table below before choosing.

Two other groups need a different response. Input problems (unattended_blocked, output_schema_unsatisfied) fail again until you change something, and a spend-cap stop (format_run_failed) needs a bigger cap or a smaller brief. The source for every row is the Errors and spend page.

The decision table

Branch on error.code after you have checked status. The set of codes is open, so keep a fallback for codes you have not seen.

Continue or re-fire

A continuation is a new run with its own id, its own receipt and its own spend cap. You name the earlier run with previous_run_id; a thread id is rejected as an unknown parameter. The earlier run must be continuable: it has a thread_id and either completed or left artifacts. Bind the same output_schema again, because it is per run and not inherited.

Re-firing with a new Idempotency-Key also creates a new run. The old key stays tied to the receipt you already have, so replaying it returns the failed run instead of trying again. That is the single most common mistake in retry loops.

What you are charged for

The docs say you pay for generation that finished before a failure or cancel, and that a later failure does not refund it. A 4xx at create, an idempotent 200 replay and a skipped run cost nothing. usage.billable_amount_usd_micros counts generation spend, not the agent's own model turn, so use usage.debited_usd_micros when you want the amount the wallet really deducted.

For format_run_failed, compare usage.billable_amount_usd_micros with usage.generation_spend_cap_usd_micros before you raise the cap. A run that tried to spend past its cap fails with this generic code, and the cap is the control you own.

A small retry policy

Put the table into code as three buckets, not nine branches.

• Continue: incomplete_assembly, agent_reported_failure, and any failure where the receipt still lists useful artifacts[].
• Retry with a new key after a pause: provider_unavailable, mcp_unavailable, deliverable_missing (once).
• Stop and alert a person: unattended_blocked, output_schema_unsatisfied, provider_credits_exhausted, and every unknown code.