Wallet 402 or spend cap: which stops a Sume holiday batch first

The wallet stops a Sume Format run only before it starts, and the spend cap stops it only while it runs. A wallet shortfall at create returns 402 insufficient_credits with next_action add_funds and no run begins. A spend cap reached mid-run ends the run failed with format_run_failed, and what it already generated is billed. For a holiday batch you want both set, because a funded wallet does not limit any one item.

The two gates

The wallet gate is a balance check when the run or queue is created. If the balance is too low the request is refused with a 402 and a next_action of add_funds, so nothing has been spent.

The cap is generation_spend_cap_usd on the run. It accepts up to $500, null means the $500 maximum, 0 is rejected as a 400, and a Format with no value of its own defaults to $400. When a run reaches the cap it ends failed rather than silently stopping.

Which one fires first

For one run, the wallet gate always comes first, because it is checked at create. Once the run exists, only the cap matters for that run. Across a bulk queue, each child is created when its slot opens, so a wallet that cannot cover a later item can refuse that child while earlier ones succeed.

Sizing a cap per item

A realistic holiday item is one 10-second Wan 3.0 clip at 720p, which is $1.25, plus a caption job at a flat $0.20, which is $1.45. A cap of $2.00 leaves room for a retry of a short step and still stops a runaway early. Over 100 items, the worst case is $200, against $145 expected.

Check usage.billable_amount_usd_micros against the cap, but know it excludes the LLM turn. The real wallet deduction is usage.debited_usd_micros, so compare the cap with the debited figure when you reconcile.

For a 100-item holiday queue, fund the wallet for the worst case ($200 at the $2.00 cap) and treat the expected $145 as the plan. Then a wallet 402 on item 80 means the balance was mis-sized, not that the cap failed.

After the run, list failed children and check each error. A format_run_failed from the cap is expected behavior; a different error code is something else and should be read before you resubmit.

• Set the cap per item, not only on the Format default.
• Keep wallet balance above the worst case, not just the expected cost.
• A failed run from the cap is a result to read, not an outage.