Budget Enforcement & Dollar Cap Administration

Budget Enforcement & Dollar Cap Administration

Arbitex Outpost enforces per-org monthly budget caps before proxying requests to AI providers. When a cap is exceeded the outpost can block requests, add a warning header, or log silently — depending on the configured action mode.

Budget configuration is part of the policy bundle delivered from the platform to the outpost. There are no separate environment variables for dollar or request caps; all values are set via the Admin Portal or API and pushed in the next policy sync.

---

How Budget Enforcement Works

Request flow

Every inbound request to the outpost /v1/chat/completions proxy passes through BudgetCapEnforcer.check() before being forwarded to the AI provider:

1. The enforcer reads budget_config from the current policy bundle.
2. It retrieves current-period usage totals from the local UsageTracker (SQLite).
3. It computes dollar_percent and request_percent against the configured caps.
4. Based on the action mode and whether a cap is exceeded, the enforcer returns an allowed/blocked result.
5. If allowed=false and action=block, the proxy returns HTTP 429 to the caller.

Fail-open guarantee

If budget_config is absent from the policy bundle (e.g. first-time deployment, bundle not yet synced), the enforcer defaults to log_only and never blocks a request. Any unexpected exception inside the enforcer is caught, logged, and the request is allowed through — a bug in budget enforcement must never take down the proxy.

Billing period

The billing period key is derived by the UsageTracker (typically YYYY-MM for monthly). Usage counters reset automatically when the period rolls over. The enforcer compares usage against the cap within the current period only.

---

Policy Bundle Configuration

Budget configuration lives in the budget_config key of the policy bundle. Set these values in the Admin Portal under Settings → Budget and they propagate to all outposts on the next policy sync (default 60-second interval).

{
  "budget_config": {
    "monthly_dollar_cap": 500.0,
    "monthly_request_cap": 10000,
    "action_on_exceed": "block"
  }
}

Field	Type	Default	Description
monthly_dollar_cap	float	0 (disabled)	Maximum estimated spend in USD per billing period. 0 or absent disables the dollar cap.
monthly_request_cap	int	0 (disabled)	Maximum number of requests per billing period. 0 or absent disables the request cap.
action_on_exceed	string	"log_only"	Action when a cap is exceeded. See Action Modes below.

---

Environment Variable Reference

The only outpost environment variable for budget enforcement is:

Variable	Default	Description
BUDGET_ENFORCEMENT_ENABLED	true	Set to false to skip all budget checks (useful for testing or emergency bypass). Dollar and request caps in the policy bundle are ignored when disabled.

---

Threshold Behaviour

Warning threshold (80%–99%)

When usage reaches 80% or more of any configured cap but has not yet exceeded 100%, the enforcer sets warning: true in its result. The proxy layer adds the response header:

X-Budget-Warning: exceeded

The request is still allowed. Use this as an early signal to raise caps or alert stakeholders.

Block threshold (100%)

When usage reaches or exceeds a configured cap and action_on_exceed = "block", the enforcer returns allowed: false. The outpost proxy responds with:

HTTP 429 Too Many Requests

The response body includes the detail message identifying which cap was exceeded (dollar, request, or both) and the billing period.

---

Action Modes

Mode	On cap exceeded	Response code	Log level	Header
block	Denies the request	429	WARNING	—
warn	Allows the request	200	WARNING	X-Budget-Warning: exceeded
log_only	Allows the request	200	INFO	—

block is recommended for production when strict spend control is required.

warn allows continued service while surfacing the overage — useful when you want visibility without hard cutoffs.

log_only (default when no budget_config is present) silently records the overage for audit purposes without affecting end-users.

---

Admin API: Budget Status

The cloud portal exposes a budget status endpoint for each org:

GET /admin/api/budget/status
Authorization: Bearer <admin-token>

Response fields:

Field	Description
period	Current billing period (e.g. 2026-03)
total_requests	Requests made in the current period
total_estimated_cost	Estimated USD spend in the current period
monthly_request_cap	Configured request cap (0 = unlimited)
monthly_dollar_cap	Configured dollar cap (0 = unlimited)
request_percent	Percentage of request cap used (0–100+)
dollar_percent	Percentage of dollar cap used (0–100+)
exceeded	true if any cap is exceeded
warning	true if usage is 80%–99% of any cap
action	Current action mode (block/warn/log_only)

---

Monitoring via BudgetPanel

The Admin Portal BudgetPanel (under Monitoring → Budget) shows:

• Current period spend vs. cap (dollar and request)
• Visual progress bars with warning (amber at 80%) and exceeded (red at 100%) states
• Action mode badge
• Per-outpost breakdown (multi-outpost deployments share the same cap counters per org)

---

Multi-Model Cost Calculation

Estimated cost is computed by the outpost’s UsageTracker using token counts from the AI provider response and per-model pricing from the policy bundle. Pricing is set in the platform admin and synced with the policy bundle.

Important: Cost estimates are computed at the outpost using token counts from provider responses. They may differ slightly from actual provider billing due to rounding, provider-specific pricing changes, or requests that fail before token counts are returned. Monitor both Arbitex-reported usage and direct provider billing dashboards for production environments.

---

Troubleshooting

False positives — requests blocked unexpectedly

Symptom: Requests blocked (HTTP 429) but usage appears low in the portal.

Checks:

1. Verify the outpost has synced the latest policy bundle. Check last_sync_at in the outpost health panel. A stale bundle may contain an outdated (lower) cap.
2. Confirm the billing period. Caps are per-period. If the period just rolled over, usage should be near zero.
3. Check BUDGET_ENFORCEMENT_ENABLED. If set to false on some outposts but not others, enforcement may be inconsistent.
4. Review the outpost logs for Budget BLOCK entries to see the exact totals and period.

Period rollover — usage not resetting

Symptom: Usage counters appear to carry over from the previous month.

Check: The UsageTracker resets counters automatically when the period key changes. The outpost must be running (not in a stopped/crashed state) at the period rollover boundary. If the outpost was down, usage from the last period may linger until the next successful request, which triggers the reset.

Resolution: Restart the outpost or wait for the next request — the reset occurs on the first check of the new period.

Budget check errors in logs

Symptom: Log entries: Budget cap check error for org=... — failing open

This indicates an unexpected exception in the enforcer, most commonly a corrupted or malformed usage_totals dict from the UsageTracker. The request was allowed (fail-open). Check the SQLite usage database (USAGE_DB_PATH) for corruption and review the full stack trace for root cause.

Action mode not taking effect

Symptom: action_on_exceed = "block" is set but requests are still allowed.

Checks:

1. Confirm the policy bundle has been synced to the outpost. Check the policy version in the outpost health panel.
2. Confirm BUDGET_ENFORCEMENT_ENABLED=true (or not set) on the outpost.
3. Verify the cap values are non-zero. A monthly_dollar_cap = 0 with action_on_exceed = "block" will never trigger (0 = no cap).