provider_credits_exhausted: why a Format run says retryable false

It is not your balance

provider_credits_exhausted means Sume's own account at the model provider ran out of credit, so the run stopped. The documentation says the cause is on the Sume side: it is not your Sume balance and not your input. details.retryable is false.

The instruction is specific: do not re-fire immediately. When Sume reports that the provider account is restored, retry with a new Idempotency-Key.

Telling it apart from the errors you can fix

A wallet problem looks different. A funding failure at create is 402 insufficient_credits with next_action: add_funds, or 402 organization_wallet_not_provisioned, and nothing ran. A spend-cap stop during the run ends as failed with the generic format_run_failed, and usage shows how close the spend got to the cap.

What to build around it

Your queue worker should have one rule for retryable: false: stop. Park the item with the run id and request_id, and let a human or a timer release it. A tight retry loop against a provider that is out of credit only produces more failed receipts.

Anything the run finished before the stop is on the thread. The documentation for neighbouring failures says finished clips are not regenerated on a retry, so a parked item loses little. Read artifacts[] on the failed receipt to see what exists.

• Do not copy the old Idempotency-Key; it is bound to the failed receipt.
• Fire the retry after Sume reports the provider account restored, not on a timer guess.
• Include the run id and request_id when you ask support; never send API keys or signing secrets.

Inside a bulk queue

A queue of up to 100 items keeps draining while children fail. A child that settles failed shows format_run_failed on the queue item. If you see many failures at once, read one child receipt before you retry the lot. A shared cause such as this one will repeat for every item you resubmit, so resubmit after the restore notice, not before.

What you can tell your own users

A customer-facing product should not say that the customer is out of credit. It is not true, and it sends them to the wrong fix. A plain message works: the render could not start because of a problem on the service side, nothing was lost, and it will be retried. Keep the item in a visible waiting state, not a failed one.

Internally, tag the item with the code and the run id so a single query can list every item waiting on the restore notice. When Sume reports the account restored, release them in batches that respect your plan's write budget. The documented per-minute write budgets are 120 on Free, 300 on Pro, 600 on Startup and 1200 on Scale, and a bulk create of up to 100 items spends one write request.

Resubmitting through a bulk queue is a good fit for this case. Mint a fresh Idempotency-Key for the new batch, because replaying a spent key returns the old queue with 202, not a new one.