Sume Format output_error codes: which to retry and which to fix

Only one Sume Format output_error code is described as transient: output_extraction_failed. Read the run once more, which alone clears a harvest_unavailable, and if it persists retry with a new idempotency key. The other codes point at your schema, your recipe or the run itself, so a plain retry would repeat the failure.

Check output_error before you read output. Per the structured output docs, an API run with an output error becomes failed, except for output_extraction_failed, where the status stays completed.

The codes

The set is open, so branch on the codes you handle and log the rest.

A failed run still shows what it made

output is null when nothing satisfied your schema, but the artifacts the run produced are still listed. In a UI, show the media and log the shape failure; a customer whose video exists is better served than by an error page. primary_output_key and primary_output_url are null on every non-completed run and whenever output_error is set, so if (run.primary_output_url) is a safe delivery test.

Make partial results legal

If a run can produce some scenes and then stop, your schema has to say a partial is a valid shape. A required array with minItems: 1 or a required non-null field turns a 20-of-40 result into output: null. Drop minItems on arrays you want received partially, and make the fields that may be missing nullable. The platform adds no minimum of its own; the schema enforces only the keywords you wrote.

• On output_schema_unsatisfied with violations[], the shape is the problem and the paths are named.
• On rejected_urls[], the run referenced URLs it did not generate; the list holds the first 10 only.
• Uploads are rejected by the URL gate, and duration_ms must be within 10% of the ledger.

A short decision list

Start with the status. A completed run with output_extraction_failed just needs a second read. A failed run with output_schema_unsatisfied needs a look at details.harvested: if the schema asks for two images and the run made one, change the schema to a nullable union or change the instruction so the run makes both. If you see deliverable_missing, the Format is meant to produce media and did not, so the fix is in the Format, not in your parser.