Enforcement

Budget enforcement

Budget enforcement lets you set spend limits on your LLM calls and have them enforced automatically by the SDK. When a user hits their limit the SDK throws a catchable error, fires a warning callback, or logs a dry-run event — depending on how you've configured it.

Budget enforcement requires a Growth plan. Configure limits in the Enforcement dashboard.

Why enforcement instead of just alerts

Alerts tell you after the fact. Enforcement stops it before the damage is done. A single misconfigured prompt or a heavy user can blow a monthly budget in hours — enforcement gives you a hard ceiling, not just a notification.

Alerts are still part of the picture. At your configured alert threshold (default 80%) the SDK fires onBudgetWarning so you can notify your team before the limit is reached. Enforcement kicks in at 100%.

How it works

The SDK maintains a spend counter per user per window. On every trackedCall() or trackedStream() call it:

  1. Looks up the active budget for this user — per-user budget first, tier template as fallback
  2. Checks the current spend counter against the limit
  3. Takes the configured action if the limit is reached
  4. Increments the counter after the call resolves
  5. Logs the event to your dashboard enforcement log

Two ways to configure limits

Tier templatesDefine a spend limit for a pricing tier — free, pro, enterprise, or any label you use. Applied automatically to every user on that tier. The right starting point for most teams.
Per-user budgetsSet a limit for a specific user ID. Takes precedence over any matching tier template. Use this to give a particular user a higher or lower cap than their tier.

Precedence

If a user has both a per-user budget and a matching tier template, the per-user budget always wins. The tier template is ignored for that user.

// Precedence order (highest to lowest)
1. Per-user budget   — exact match on userId
2. Tier template     — match on tier tag
3. No enforcement    — call proceeds normally

Actions

warnCall proceeds. onBudgetWarning fires. A budget_event is logged. Recommended default — safe to deploy without additional error handling.
blockCall does not proceed. LLMBudgetExceededError is thrown. Must be caught in your code — see Handling blocks.
dry_runCall proceeds. A console warning is logged. No error thrown. Use this to validate your budget config before going live.

Windows

Spend counters reset at the start of each window period. All windows are calculated in UTC.

dayResets at 00:00 UTC each day.
weekResets at 00:00 UTC each Sunday.
monthResets at 00:00 UTC on the 1st of each month.

Next: Tier templates →