A circuit breaker for paid video API calls: cap, poll, cancel

A circuit breaker for paid video API calls needs three layers: a spend cap on every request, a counter in your own code that stops starting new runs after repeated failures, and a cancel call for runs already in flight. Sume gives you the first and third; the middle one is yours.

The cost of getting it wrong is real money. A retry loop that creates a new paid run on every failure turns one bad input into a bill.

Treat spending as a first-class failure mode, not an afterthought. A function that creates a paid run should be the single place that checks the breaker, so no code path can skip it.

Layer one: the cap on the request

Every Format run accepts generation_spend_cap_usd, which must be above zero and at most 500. A Format with no cap defaults to $400, and null means $500. The API does not clamp a number above the Format's own cap, and the effective cap is echoed back in usage.generation_spend_cap_usd_micros. Send a small number deliberately. The Call a Format page has the field.

A run that tries to exceed the cap ends failed with format_run_failed instead of spending past it. That is the platform-side stop.

Layer two: a breaker in your code

Count terminal failures per Format over a window. When the count passes a threshold, open the breaker: stop creating runs for that Format, alert a person, and let the half-open state allow a single canary after a pause. Do not count mcp_unavailable, which is not charged and usually passes by itself.

Never loop on provider_credits_exhausted. It is marked not retryable, and the right response is to open the breaker immediately.

Pick thresholds from your own volume. A pipeline that makes ten videos a day can open after three failures; one that makes a thousand needs a percentage over a window, otherwise one bad hour opens the breaker for no reason.

Layer three: cancel what is running

Each receipt includes a cancel_url. Calling it is idempotent and returns a cancel_effect of canceled or no_op. You still pay for generation completed before the cancel, so cancel early, not after a long wait. A canceled run never delivers a webhook, so update your own row when you cancel.

In bulk, there is no cancel for a queue. Cancel the child runs one by one using the run ids on the queue's items. The Bulk runs page explains the limitation, and it is a good reason to keep concurrency low until a Format has proven itself.

If you only remember one rule from this section, make it this: cancel is cheap, waiting is not. Run the cancel from the same code that sets your timeout so the two cannot drift apart.

Put a clock on it

Every run has an expires_at, which is a force-finalize deadline: 90 minutes from creation, or sooner when a run older than 25 minutes has been silent for 10. Long-form video typically takes 15 to 30 minutes, so a timeout of 45 minutes in your own code is a sane alert threshold. Poll with a doubling backoff up to 60 seconds, and when the clock runs out, cancel and record why.

The same pattern applies to Agent Completions, where the cap is required on every request rather than defaulted. See Agent Completions.