Spend caps

Spend caps let you limit how much API usage can cost over a rolling time window. You configure them in your dashboard under Organization settings → Spend caps. You can also set per-key caps when editing an API key's scope.

Spend caps are separate from your credit balance. A request can fail with insufficient_credits when you are out of credits, or with spend_cap_exceeded when a configured cap would be exceeded. Both return HTTP 402.

Scope types

Each spend cap applies to one scope. Usage is measured from completed API requests billed in USD (costUsd).

You can enable multiple caps at once. For example, an org cap, a project cap, and a per-key cap can all apply to the same request.

How caps stack

Each enabled cap is evaluated on every request. Usage counts toward every cap that applies at once.

• Block mode: when settled spend in the rolling window (plus the estimated cost of the current request) reaches 100% of the limit, the gateway rejects the request with HTTP 402 and error code spend_cap_exceeded.
• Warn mode: when utilization reaches 80% or higher, Sansa logs a warning and can send notification emails. Warn caps do not block requests.

Caps do not compound into a single shared budget. A $100 org cap and a $50 project cap are two independent limits. Either one can block traffic when exceeded in block mode.

Rolling windows

Every cap has a window measured in days (1 to 365). Spend is summed over the last N days, not calendar months.

When you set a per-key daily or 30-day cap in the key scope editor, Sansa stores the matching SpendCap rows (1-day and 30-day windows). The organization spend caps page is a central place to view, create, or delete caps at any scope, including API keys.

If you create a cap for the same scope and window twice, the second save updates the existing cap instead of creating a duplicate.

Where to configure caps

Organization spend caps (central hub)

Go to Organization settings → Spend caps in your dashboard. From there you can:

• Add caps at organization, project, environment, or API key scope
• Choose limit amount, window length, and block vs warn
• For API key scope, pick the key by name from a dropdown
• Filter, search, and delete caps

Organization owners and admins can manage spend caps.

Per-key scope editor

When creating or editing an API key, open the Spend cap section in the key scope sidebar. You can set optional daily and 30-day window limits and choose block or warn. The same caps appear in the organization spend caps list.

Plans and entitlements

Contact support if you need granular caps on a Free plan.

Block error messages

When a block-mode cap would be exceeded, the API returns:

{
  "error": {
    "code": "spend_cap_exceeded",
    "message": "This request would exceed the 30-day spend cap for this organization.",
    "request_id": "a3f2c1d0-8b4e-4f9a-b2d1-7c5e3a1f0e9b"
  }
}

The message names the scope and window of the cap that blocked the request:

Examples

• Organization, 30-day window: This request would exceed the 30-day spend cap for this organization.
• Project, 7-day window: This request would exceed the 7-day spend cap for this project.
• Environment, daily: This request would exceed the daily spend cap for this environment.
• API key, 30-day window: This request would exceed the 30-day spend cap for this API key.

If more than one block-mode cap is exceeded on the same request, the message reflects the most specific scope: API key, then environment, then project, then organization.

See Errors for the full error reference, including how spend_cap_exceeded differs from insufficient_credits.

Handling spend cap errors in code

Spend cap blocks use the same HTTP 402 status as credit exhaustion, but a different error.code. Check the code field to tell them apart.

Python

except openai.APIStatusError as e:
    code = e.body.get("error", {}).get("code")
    if e.status_code == 402 and code == "spend_cap_exceeded":
        print("Spend cap reached:", e.body["error"]["message"])
    elif e.status_code == 402:
        print("Add credits from your dashboard")

TypeScript

} catch (err) {
  if (err instanceof OpenAI.APIError && err.status === 402) {
    const code = (err.error as { code?: string })?.code;
    if (code === "spend_cap_exceeded") {
      console.error("Spend cap reached:", err.error.message);
    } else {
      console.error("Add credits from your dashboard");
    }
  }
}

Do not retry spend_cap_exceeded until the rolling window spend drops or you raise the cap.

Related topics

• Errors — Full error codes, including insufficient_credits and spend_cap_exceeded
• Organization settings in your dashboard — Billing, credits, and spend cap configuration