Overage protection
Overage protection is a workspace-level safety rail for platform-metered chat completions (traffic billed through Rikaii’s catalog and shared upstream keys). When enabled, the gateway may lower the effective max_tokens or max_completion_tokens you sent so the call cannot burn more estimated retail output than your remaining budget allows.
It does not replace sound application design—you should still set reasonable limits in your client—but it catches accidental “infinite” or multi-million-token requests and aligns long completions with prepaid balance, per-key credit limits, and monthly spend caps configured in the Dashboard.
When it applies
| Condition | Behavior |
|---|---|
| Platform-metered (PAYG-style) route | Protection may compute a budget-derived completion cap and merge it with your request and catalog hard limits. |
| BYOK-satisfied route | Protection is skipped for budget capping—upstream billing is primarily on your provider account; Rikaii does not apply the same retail headroom calculation to your completion ceiling. |
| Toggle off in Dashboard | No budget-derived cap; catalog and sanitization rules still apply. |
The toggle defaults on for new workspaces; operators can change it under workspace / billing settings in the Dashboard.
How the effective completion cap is chosen
For each eligible request, the gateway builds an outbound payload to the upstream provider. The completion budget field sent upstream is either max_tokens or max_completion_tokens depending on the resolved model family (reasoning-first SKUs often require the completion-tokens field).
The value ultimately sent is the minimum of every applicable positive ceiling:
- What you asked for —
max_tokensand/ormax_completion_tokensfrom your JSON (the gateway coalesces them per family rules). - Catalog hard ceiling — the resolved upstream model’s configured maximum output tokens (and a conservative default when the catalog cannot pin a row).
- Budget cap (overage protection) — optional integer computed from remaining USD headroom divided by marginal retail price per output token for that catalog row, after reserving an estimated prompt retail charge.
If only some dimensions exist, only those participate. If none bound the completion field, the outbound request may omit an explicit cap when allowed by the provider adapter.
Budget headroom (intuition)
Headroom is roughly “how many more dollars can this workspace still spend on metered traffic before hitting a limit,” considering:
- Monthly retail spend cap (when set), minus calendar-month retail spend to date, minus a small safety margin so you do not skim the cliff edge on the last request of the month.
- Per-key credit limit (when set on the API key), minus current-period spend on that key.
The tighter of workspace vs key headroom wins when both exist.
The gateway uses a fast character-based prompt estimate (not a full tokenizer) so the cap errs slightly conservative—better a shorter completion than an unexpected 402.
Hard stops before the upstream call
When overage protection is on and the math says there is no room left after the estimated prompt charge—or the affordable completion budget rounds below one token—the API returns 402 Payment Required with an OpenAI-shaped error object instead of calling the provider. Treat 402 like a billing signal: adjust limits, add balance, reduce prompt size, or switch to a cheaper model slug.
Interaction with rate limits
Rate limits (429) throttle request count per minute. Overage protection throttles how large a single completion may grow in tokens. They are independent; you can hit either without having hit the other.
Related
- Chat completions — where caps appear in the outbound contract and
usage - Understanding Cost Avoidance
- Macroscopic invoicing
- Routing engine