Caps and credits
Compare base spending allowances with consumable product-user credit grants.
Zorveus provides two distinct controls to govern AI expenditures: spending caps and credit grants.
Caps and credits at a glance
| Feature | Spending cap | Credit grant |
|---|---|---|
| Purpose | Base virtual allowance for a period | Consumable credits owned by one product user |
| Reset behavior | Resets periodically (daily, monthly, or lifetime) | Non-replenishing, expires at set date or consumed to zero |
| Applied to | Organization, app connection, product user | Product user in one application |
| Enforcement | Rejects when base allowance plus credits are exhausted | Extends base allowance before requests are rejected |
| Funding source | Organization wallet or BYOK | Granted by your application, extends virtual allowance |
Spending caps
A spending cap sets the base virtual allowance over a period:
- Evaluated during pre-flight token reservation.
- Configured across daily, monthly, or lifetime periods.
- Rejection returns
403 Forbiddenwith error codezorveus_cap_exceededorzorveus_product_user_allowance_insufficient. - Caps apply at three distinct levels:
- Organization cap: overall organization spend limit.
- Connection or key cap: specific limit for an app connection or API key.
- Product-user cap: per-user base allowance on that key.
If an inference key has no cap rule, virtual allowance is unlimited across all credit modes. Requests pass through, virtual spend is recorded, and zero product-user credits are consumed. Credits extend a configured cap, but they do not create a cap where none exists.
Product-user credit grants
A credit grant assigns spendable credit to one product user:
- Multiple grants stack additively.
- Eligible grants are consumed by earliest expiry first.
- Grants are not organization wallet funds. Granting credits does not deposit money into the organization wallet, and consuming credits does not pay an upstream model provider.
- Read remaining balances through the service-key API by external user ID. Revoke credit grants in the dashboard.
Allowance formula and consumption order
When an inference key has a configured cap, the available allowance is:
remaining allowance = remaining base allowance + available product-user creditsThe remaining base allowance is:
remaining base allowance = max(0, cap amount - completed period virtual spend - active reservations)Consumption order: base cap first
Usage consumes allowance in this order:
- Remaining base allowance on the key.
- Available product-user credits (oldest expiring first).
- Uncovered virtual spend (in non-blocking track-only mode or request overruns).
For example, on a $10 monthly cap with $8 spent so far, the user has $2 base allowance remaining. If the user holds $5 in credits and sends a request estimated at $3, Zorveus reserves the first $2 from the base cap and only $1 from credits.
Allowance overrun policies
App connections configure an overrun_policy that controls what happens when a model response exceeds remaining allowance:
| Policy | Behavior on active request | Excess virtual spend | Future allowance |
|---|---|---|---|
limit_output (default) | Reduces provider max tokens to the affordable amount | Records unexpected variance as uncovered | No planned debt |
allow_overrun | Lets the request run to declared or safe limit | Records excess as uncovered virtual spend | Forgiven when new allowance becomes available |
carry_overrun_forward | Lets the request run to declared or safe limit | Records excess as uncovered spend and debt | Repaid from later credit grants or next base cap reset |