Suppose a document-processing agent reaches its budget at noon with half the queue still waiting. Should it pause until the reset, use another approved model, or ask an operator for more capacity?
Choose that behavior before setting the limit. The application needs a response it can explain to the people waiting for their documents.
Decide what the application does when the budget runs out
Consider a hypothetical document-processing service. Interactive requests have a service commitment; background enrichment can wait. The following worksheet separates the controls and the application response.
| Exhausted scope | Intended control behavior | Application response to define |
|---|---|---|
| One model member inside an approved pool | Skip the exhausted member when another eligible member can serve | Continue only if the alternate satisfies the workload contract |
| Agent's daily budget | Refuse affected calls when that applicable budget is exhausted | Pause the agent's queue; notify the responsible operator through the team's chosen process |
| Pool or gateway budget | Refuse affected traffic within that scope | Return an explicit service condition rather than retrying other aliases blindly |
| Workspace budget | Refuse affected traffic despite remaining lower-scope headroom | Escalate to the budget owner; do not route around the shared ceiling |
| Direct model connection budget | Refuse the direct request; no pool spillover path | Use the application's defined failure or queue behavior |
Your application must implement the queue and notification steps. Setting a Dome quota doesn't create that recovery workflow.
Dome's Quota model checks every applicable enabled budget. A lower-scope budget with room cannot override an exhausted broader one. Model-member exhaustion inside a pool is different from exhausting the pool's aggregate budget.
What is capped, and when does it reset?
Record who owns the budget, what it measures, which workload it constrains, and when its window resets. Dome documents daily and monthly windows using UTC calendar boundaries. Make that visible to the service team instead of assuming the budget resets at the operator's local midnight.
Also record who may approve a temporary increase and the evidence required. A quota edit is not a fresh accounting period: usage already recorded in the window remains relevant.
For the document service, the owner might approve additional capacity for an identified backlog. That is different from raising the cap whenever the application sees a refusal.
A different model is still a permission decision
A cheaper or less-used model is not automatically an acceptable substitute. Use the model-pool contract to establish which destinations preserve the data and output requirements.
If one model member is exhausted, another eligible member can preserve service. If the workspace budget is exhausted, trying a different pool name should not be the recovery procedure. It is the same shared budget decision.
Limit retries in the application. Retrying the same refused call won't restore the budget; it just keeps the queue busy.
Don't mistake a usage cap for a guaranteed provider bill
Dome documents distributed enforcement: a straddling call or in-flight traffic can create usage beyond the point at which a cap becomes visible everywhere.
For units Dome bills, the documented billing treatment excludes qualifying excess from billing. Estimated upstream provider cost is different: Dome does not issue that provider invoice, and the estimate is not clamped into a guaranteed provider-bill ceiling.
The distinction matters when finance signs off the contract. “Stop future traffic as the budget is exhausted” and “the external invoice cannot exceed this number” are different promises.
Opaque passthrough model calls also do not add priced token spend from their opaque bodies, even though quota checks still apply. Account for such paths before claiming the chosen meter covers the service.
Test with a small budget before production
Use a controlled environment and synthetic workload. Set a deliberately small test budget, observe the actual refusal or eligible spillover, and confirm the queue or client response. Include the broader-scope exhausted case as well as the individual-member case.
Do not run that exercise against a shared production budget without an approved plan. Check that the test cannot interrupt unrelated workloads.
Keep the observations with the contract: scope, dimension, window, expected behavior, actual behavior, escalation owner, and recovery criteria. The queue should have a clear next step when a call is refused.