A Sume bulk queue item failed: read the child receipt first

When a bulk queue item shows failed, the queue only tells you format_run_failed or, for an item that never started, a create-run code. The reason is on the child run: fetch GET /v1/format-runs/{run_id} and read its error, output_error and usage. Then decide whether to retry, raise the cap, or fix the input.

What the queue item can tell you

Triage in this order

• run_id is null: the item never began. The error is an admission failure such as a wallet or concurrency problem. Fix that and resubmit that item.
• usage.billable_amount_usd_micros against usage.generation_spend_cap_usd_micros: a run that tried to spend more than its cap fails with the generic code, so a spend at the cap points to a cap that is too low.
• output_error: if you bound an output_schema, check why the projection failed before reading output.
• filled_by: projection means the run did not submit the object itself.
• Otherwise read the run events through events_url on the receipt.

Retry without paying twice for the same work

To retry a failed run with context, send its id as previous_run_id on a new run of the same Format. That continues the conversation as one more turn instead of starting over. For a batch, put the retry items in a new queue with a new Idempotency-Key. A replayed key returns the old queue, so reusing the key will not retry anything.

A narrow retry is cheaper than a full one. If the failure was a single scene, tell the new turn which scene to redo in the instruction and let previous_run_id carry the rest. Read the first run's output for the scenes that did finish so that the instruction can say what to keep.

Design for partial results

If one slot of a multi-scene video fails, a strict schema can turn a mostly good run into output: null. Make optional fields nullable and avoid minItems on arrays you want to receive partially. Pair that with a primary_output_key so a run without the deliverable still ends as failed with primary_output_missing, while the good scenes remain readable.

Do not cancel the queue

There is no cancel-queue endpoint. If a batch is going wrong, cancel the child runs with POST /v1/format-runs/{run_id}/cancel. The queue marks each as canceled and starts the next queued item, so cancel children from the back of the list first or the window will refill.