Budget Gates
Block requests when an organization or model budget is exceeded — per-org and per-model enforcement.
Budget Gates
Budget gates block, alert, or downgrade requests when org spend exceeds a configured budget.
Tier: Requires Growth tier or higher (budget_enforcement is a non-free feature).
Feature flag: BUDGET_GATE_ENABLED — defaults to OFF. Enable per-environment after validation.
How It Works
The gateway checks your org's current spend against configured budgets before forwarding each request. Three actions are supported:
| Action | Behavior |
|---|---|
block | Return 429 with error message (current spend + budget) |
downgrade | Rewrite request model to a cheaper alternative |
alert | Allow request through (notifications are deferred) |
Configuration
Budgets are configured via the CoreValue dashboard or API. The gateway fetches budget config from Core with a 60-second cache.
Per-Org Scope
Budgets apply to all requests (BYOK + PTB) — total org spend. When an org has BYOK keys, the action is forced to alert (since BYOK requests don't deduct PTB credits).
Downgrade Mappings
When action is downgrade, the gateway rewrites the request model to a cheaper alternative from the downgrade mapping table. If no mapping exists, the request is blocked.
Fail-Open Behavior
On any failure (Core down, Postgres down, Redis down), the gateway allows the request. Budget gates never block traffic due to infrastructure failure.
Response Format
Block (429)
{
"error": "Budget exceeded",
"current_spend": 105.00,
"budget": 100.00
}Downgrade
The response includes the original and downgraded model in Cova-* headers. The request proceeds with the cheaper model.
Enabling Budget Gates
- Set
BUDGET_GATE_ENABLED=truein your gateway environment - Configure budgets via the CoreValue dashboard
- Set up downgrade mappings (optional)
- Monitor the budget breach log in the dashboard
Related: Escrow provides reserve-before-execute for concurrent request protection. Disallow List blocks specific models or providers.