A customer-support API has three limits that fail in different ways: budgets constrain planned spend, balances authorize billable consumption, and quotas control request volume. The assistant still needs to keep answering tickets without letting one customer consume more than the contract permits. That operational constraint changes the design because these controls need separate state and separate failure policies.
Short answer: a budget crossing should alert or deliberately refuse expensive work; an insufficient balance should reject the billable operation before execution; a quota crossing should delay or refuse traffic within a defined time window. Combining all three into one remaining number makes retries, refunds, and burst traffic corrupt the meaning of that number. For a metered invoice, record an immutable usage event, reserve funds before costly work, and make quota decisions independently.
How do budgets, balances, and quotas make three API limits fail differently?
A budget is a planning boundary. It asks, "How much are we willing to spend during this accounting period?" The useful input may be an estimate because the final usage event does not exist yet. A support team might allow the last ticket that takes projected spend over the warning threshold, switch to a cheaper processing path, or refuse it. That is a product decision, not an accounting truth.
A balance is accounting state. It asks, "Does this customer have enough settled or reserved value for this billable operation?" Debits, credits, reservations, releases, and adjustments belong in a ledger. A mutable creditsRemaining column is tempting, but it loses the explanation for a value after duplicate delivery or a reversed operation. For invoicing, the explanation matters as much as the total.
A quota is traffic policy: 300 ticket analyses per hour, five concurrent exports, or some other count over a named scope and window. It protects capacity and expresses an entitlement. Waiting can fix a windowed quota failure. Waiting does not replenish a depleted balance, and it does not make an intentionally fixed monthly budget larger.
The simple approach fails because the units differ. A budget can be denominated in projected currency, balances in billable credits, and quotas in API requests per interval. Even if two happen to use the same unit today, their clocks and correction rules still differ. The distinction is explained by what restores permission: a new policy decision for the budget, a ledger credit for the balance, or elapsed time and released capacity for the quota.
One counter cannot express that.
| Control | Question answered | Typical scope | Crossing behavior | Correction path |
|---|---|---|---|---|
| Budget | Should more spend be allowed? | Customer and billing period | Warn, degrade, or refuse by policy | Raise cap or begin a new period |
| Balance | Can this operation be paid for? | Customer ledger | Refuse before billable work | Credit, release, or adjustment entry |
| Quota | May this traffic run now? | Key, customer, route, and window | Delay or refuse | Wait for capacity or the next window |
Three controls. Three clocks.
Put the refusal at the correct boundary
For customer support, the expensive mistake is checking after an answer has already been generated. The customer receives value, the runtime incurs usage, and the billing system then discovers that authorization should have failed. Check the estimate first and reserve the maximum permitted amount. After execution, settle the reservation against measured usage and release the difference. If execution fails before producing billable value, release it with an idempotent operation.
Quota admission happens beside that flow, but it is not a ledger entry. A request can have sufficient funds and still exceed concurrency. It can also fit the quota while lacking balance. Return distinct machine-readable reasons so callers know whether retrying later is sensible. Keep the public message calm; put the precise control, scope, and decision ID in structured telemetry.
Budget policy sits above both. Consider an interactive ticket reply estimated at 40 units when the customer has 50 units of available balance, one quota slot, but only 30 units left in the period budget. The balance check passes. The quota check passes. Only the budget policy has a decision to make: refuse, choose a lower-cost path, or permit a 10-unit overrun. For the interactive reply, accepting bounded variance may avoid abandoning an agent mid-conversation. For a bulk reprocessing job, refusal at the same ceiling is easier to defend because no person is waiting. This is an explicit trade-off: a harder ceiling produces more refused traffic, while a softer ceiling permits spend variance. There is no universal setting, and hiding this choice inside a shared counter merely makes it impossible to audit later.
This focused TypeScript example keeps the controls separate and returns a decision that can be persisted with the usage event:
type Request = {
customerId: string;
operationId: string;
estimatedUnits: number;
};
type ControlState = {
budgetRemaining: number;
availableBalance: number;
quotaRemaining: number;
};
type Admission =
| { allowed: true; reservationUnits: number }
| { allowed: false; reason: "budget_exceeded" | "balance_insufficient" | "quota_exhausted" };
function admit(request: Request, state: ControlState): Admission {
if (request.estimatedUnits <= 0) {
throw new Error("estimatedUnits must be positive");
}
if (state.quotaRemaining < 1) {
return { allowed: false, reason: "quota_exhausted" };
}
if (state.availableBalance < request.estimatedUnits) {
return { allowed: false, reason: "balance_insufficient" };
}
if (state.budgetRemaining < request.estimatedUnits) {
return { allowed: false, reason: "budget_exceeded" };
}
return { allowed: true, reservationUnits: request.estimatedUnits };
}
The function is intentionally boring. Production correctness lives around it: atomically consuming quota, creating a unique reservation for operationId, and settling exactly once. A read followed by a later write is unsafe under concurrency because two workers can observe the same remaining amount. Put the compare-and-update in one transactional boundary supported by the state store.
Failure handling is part of the invoice
Retries are normal delivery behavior, so operationId must identify the logical support action rather than an individual network attempt. Reusing it should return the prior reservation or settlement result. A new retry ID can charge twice. This is the sharp edge.
Do not make a timed-out caller proof that work failed. The server may have completed after the client stopped waiting. The caller should query or retry with the same idempotency identity; the meter should reconcile from durable execution and settlement records. Likewise, a delayed usage event must be applied to the accounting period defined by the billing policy, not whichever wall-clock window happens to be open when a consumer catches up.
Negative corrections deserve named ledger entries. Editing an earlier event destroys the audit trail, while silently clamping a balance to zero hides a mismatch. Append a compensating entry that refers to the original operation and preserves both amounts. The invoice total can then be reproduced without trusting a mutable aggregate.
Quota storage has a different recovery story. If a window counter is temporarily unavailable, the team must choose fail-open or fail-closed by operation. Letting a low-cost ticket classification through may be acceptable. Starting a large batch export without a concurrency lease may not be. Document that choice per operation; a global fallback flag is too blunt.
Keep credentials out of metering state
Customer identity, authorization, and secret handling surround these controls but should not be collapsed into them. A credential proves which principal is calling. It does not prove that a budget remains, and rotating it must not reset a customer's quota or ledger balance. Key control state by a stable internal customer identifier, then map authenticated principals to that identifier.
The OWASP Secrets Management guidance recommends centralizing and standardizing secrets management, applying least privilege, and planning rotation and revocation. Those practices matter here because a leaked credential can generate apparently valid usage. Store secrets in the designated secrets system, avoid placing them in usage events or logs, and retain only the non-secret identifiers needed to investigate a decision.
Never put a secret in the ledger.
What should you measure before adopting this design?
Measure refusals separately by reason, scope, and operation. A rising quota_exhausted count suggests a traffic-shaping or entitlement issue; balance_insufficient points toward funding or reservation release; budget_exceeded reflects the chosen spend policy. One generic rejection metric erases the distinction the architecture worked to preserve.
Also track reservation age, unsettled reservation count, duplicate operation attempts, correction entries, estimate-to-measured variance, and the time between execution and settlement. Alert on stale reservations and reconciliation mismatches rather than on ordinary quota refusals. Refusal may be correct behavior. Drift is not.
Before copying the approach, run four cases under concurrency: two requests competing for the last available balance, a retry after an ambiguous timeout, a successful operation whose measured usage is below its reservation, and a quota window rollover while work is in flight. Then decide the spend ceiling versus refused-traffic trade-off for each support operation. The design is working when every accepted charge is reproducible and every refusal names the control that made it.
Sources
- OWASP, "Secrets Management Cheat Sheet": https://cheatsheetseries.owasp.org/cheatsheets/Secrets_Management_Cheat_Sheet.html
Top comments (0)