Budgets

Budgets protect managed AI spend at the organization, environment, caller API key, provider key, team, or member level. The managed control plane tracks usage and makes budget decisions, and the gateway enforces those decisions before calling an upstream provider.

Budget enforcement requires an AISIX managed control plane. A self-hosted gateway does not have a budget enforcement engine.

Budget Configuration

Create and edit budgets from the Budgets view in the managed control plane. Choose the target type, then select the organization, environment, key, team, or member whose spend the budget should control. Because caller API keys belong to an environment, select the environment before selecting an API key target.

Resource views also provide inline budget controls as shortcuts. These controls appear in the API key list, provider key list, Members view, and team detail page. The team detail page includes both the shared team budget and its per-member budget. An inline control and the Budgets view edit the same budget, so changes made in either location appear in both.

A target can hold one budget. Edit that budget to change its limit, period, or enforcement mode. Create another budget when you need to control a different target.

For each budget, configure:

• A target, such as an organization, environment, caller API key, provider key, team, member, or each member in a team.
• A spending limit in USD.
• A day, week, or month period.
• An enforcement mode. A blocking budget can reject traffic after the limit is reached. A warn-only budget keeps traffic flowing and surfaces the over-budget state in the control plane.
• Alert thresholds, as percentages of the limit (default 80%). Crossing a threshold sends a notification through the organization's notification channels — see Budget Alerts and Notifications.

Budgets are managed-control-plane resources. They are not created through the self-hosted AISIX Admin API.

Budget Targets

Choose the narrowest target that represents the spend you want to control:

Target	Spend counted toward the budget
Organization	All managed traffic in the organization
Environment	Traffic in one deployment environment
Caller API key	Traffic authenticated with one downstream application or tenant key
Provider key	Usage attributed to models that use one upstream credential or provider account
Team	Traffic from every caller API key bound to one team
Member	Traffic from every caller API key bound to one member, across the organization
Each member in a team	A separate allowance for each member's traffic through keys bound to one team

Team and member budgets depend on the identity stored on the caller API key. A key can carry a team binding, a member binding, both, or neither. Team membership by itself does not make a key's spend count toward that team. Only the bindings on the key used for the request determine which budgets apply.

Provider-key accounting follows the credential attached to the model in each usage record. Pre-dispatch enforcement happens earlier: the control plane checks provider-key budgets for credentials available to the caller API key's environment. An exhausted blocking provider-key budget can therefore reject a request authenticated with that key before routing selects a different credential in the same environment.

A member budget and an each-member-in-a-team budget count different traffic:

• A member budget is organization-wide. It combines spend from every caller API key bound to that member, regardless of the key's team binding.
• An each-member-in-a-team budget gives every member a separate limit within one team. It applies only when the caller API key carries both that team binding and a member binding.

If a team or member budget counts unexpected traffic, inspect the bindings on the caller API key that reached the gateway.

Example: One Member in Two Teams

Suppose Alice belongs to the frontend and data teams and uses three caller API keys:

Key	Team binding	Member binding
K1	frontend	Alice
K2	data	Alice
K3	none	Alice

The organization configures these monthly budgets:

• Alice has a $300 member budget. Spend from K1, K2, and K3 counts toward this organization-wide limit because all three keys are bound to Alice.
• The frontend team has a shared $1,000 budget. Spend from every key bound to frontend counts, including K1 and keys bound to other members or to no member.
• Each member in frontend has a $100 limit. Only K1 counts toward Alice's allowance because it carries both her member binding and the frontend team binding. Every other member gets an independent $100 allowance.

Traffic through K2 does not count toward either frontend budget. K3 does not count toward a team budget, even though Alice belongs to two teams, because the key has no team binding.

A request through K1 is checked against every matching budget. These include the frontend team budget, Alice's member budget, her frontend member allowance, and any matching organization, environment, caller API key, or provider key budget. Any matching blocking budget that has reached its limit rejects the request.

Enforcement Path

Applications continue to use the same proxy API and caller API key after a budget is configured. They do not call a separate budget API.

Before AISIX sends a provider request, the managed gateway asks the control plane whether the caller can continue. If every matching blocking budget has room, the request follows the normal proxy path. Usage from that request can put a budget over its limit after the provider responds; a later check then rejects matching traffic before the provider call.

Budget Rejection Response

For OpenAI-compatible requests, a budget rejection returns 429 with an OpenAI-style error envelope:

{
  "error": {
    "message": "api key budget 'production-chat' exceeded ($1.00/month). Resets 2026-06-01 00:00 UTC.",
    "type": "billing_error",
    "code": "budget_exceeded",
    "scope": "api_key",
    "scope_ref": "api-key-uuid-1",
    "limit_usd": "1.00",
    "spent_usd": "2.00",
    "period": "month",
    "period_resets_at": "2026-06-01T00:00:00Z",
    "retry_after_seconds": 259200
  }
}

Anthropic-compatible Messages requests keep the Anthropic error format and do not include the additional budget fields.

Availability and Caching

The gateway caches managed budget decisions for 5 seconds, so repeated requests do not always require a control-plane round trip.

If the control plane becomes unreachable, AISIX can reuse a stale cached decision up to the ceiling set by AISIX_DP_BUDGET_STALE_MAX_SECONDS. This process environment variable defaults to 600 seconds. If no cached decision exists, AISIX denies the request.

Within the stale ceiling, sticky mode reuses the last decision: previously denied keys stay denied, and previously allowed keys continue. After the ceiling expires, AISIX applies the outage behavior returned by the control plane:

• Sticky mode refuses traffic because the cached decision is too old.
• Fail-open mode allows traffic.
• Fail-closed mode refuses traffic.

This cache and outage behavior applies only to managed budget checks.

Budget Usage Metrics

The control plane tracks budget usage from managed traffic. When a budget response includes totals, AISIX records budget gauges with the caller API key ID and, when available, the projected team and member IDs. If a decision omits budget totals, AISIX clears the gauges for that key identity.

Review Budget Rejections

When a managed deployment returns budget_exceeded, inspect the error code and structured budget fields first. The denial came from the managed budget-check response, not from the Admin API.

Find the returned target in the Budgets view and review its limit, period, and enforcement mode. If the scope is unexpected, inspect the team and member bindings on the caller API key used for the request.

Next Steps

Configure Budget Alerts and Notifications to receive a webhook or Slack message when a configured threshold is reached. Then continue with Rate Limits to configure request, token, and concurrency limits.