Per-key limits and budgets

Every API key can carry its own budget and access rules, so you can hand a key to a teammate, a script or a customer without risking your whole balance. Set them when you create or edit a key in API Keys.

All limits are in USD of actual cost, after the group multiplier. The key also stops when your account balance runs out (403 INSUFFICIENT_BALANCE), whatever its own limits say.

#How the spend windows work

The 5-hour, 1-day and 7-day limits use fixed windows, not rolling ones. A window starts when the key is first used after the previous window ended, and resets once its full duration has passed. For example, with a $5 daily limit, a key first used at 14:00 can spend $5 until 14:00 the next day, and then gets a fresh $5.

When a window is used up, requests fail with HTTP 429, error type rate_limit_exceeded, and a message such as api key 5小时限额已用完 ("the key's 5-hour limit is used up"). There is no Retry-After header. Read reset_at from /v1/usage to know when to resume.

A request that is already running can finish and go slightly over a limit; the next request is blocked.

#What keys cannot limit

• Models. There is no per-key model allow-list. A key can call every model its group serves. To restrict models, use a key in a different group.
• Request rate. There is no per-key requests-per-minute or concurrency setting. Rate and concurrency limits apply per account and per group. See Limits & rate limits.

For a cap across all your keys, set the weekly and monthly account spend caps on Balance & billing. Reaching one returns 402 spend_cap_reached until the reset; see Billing & top-ups.

#Read limits with GET /v1/usage

GET /v1/usage returns the calling key's limits and usage. It works even when the key is expired or out of quota, so a script can always check why it stopped.

curl https://bigmodel.io/v1/usage \
  -H "Authorization: Bearer $BIGMODEL_API_KEY"

import os, requests

r = requests.get(
    "https://bigmodel.io/v1/usage",
    headers={"Authorization": f"Bearer {os.environ['BIGMODEL_API_KEY']}"},
    timeout=10,
)
data = r.json()
print(data.get("status"), data.get("remaining"))
for w in data.get("rate_limits", []):
    print(w["window"], w["used"], "/", w["limit"], "resets", w.get("reset_at"))

const r = await fetch("https://bigmodel.io/v1/usage", {
  headers: { Authorization: `Bearer ${process.env.BIGMODEL_API_KEY}` },
});
const data = await r.json();
console.log(data.status, data.remaining);
for (const w of data.rate_limits ?? []) console.log(w.window, w.used, "/", w.limit, "resets", w.reset_at);

A key with a quota or a spend window returns "mode": "quota_limited". Abbreviated example:

{
  "mode": "quota_limited",
  "isValid": true,
  "status": "active",
  "quota": {"limit": 20, "used": 3.42, "remaining": 16.58, "unit": "USD"},
  "remaining": 16.58,
  "unit": "USD",
  "rate_limits": [
    {"window": "1d", "limit": 5, "used": 1.2, "remaining": 3.8,
     "window_start": "2026-10-18T06:00:00Z", "reset_at": "2026-10-19T06:00:00Z"}
  ],
  "expires_at": "2026-11-17T00:00:00Z",
  "days_until_expiry": 30,
  "usage": {"today": {"requests": 12, "cost": 0.4, "actual_cost": 0.4}, "total": {"requests": 310}}
}

• status is active, quota_exhausted, expired or disabled.
• quota appears only if the key has a quota; rate_limits only lists windows that are set. reset_at is missing when the window has not started or has already ended.
• A key without a quota or spend windows returns "mode": "unrestricted" with your balance (or plan limits for a plan group) in remaining. Expiry is not included in that mode.
• usage has today and total request, token and cost counters. Add ?start_date=2026-10-01&end_date=2026-10-18 to set the date range of model_stats (default: last 30 days).

The full schema is in the Usage API reference.

#Verify the setup

Create a key with a small 1d limit, for example $0.10, and call GET /v1/usage with it. The response should be quota_limited and list a 1d window with limit: 0.1. Send a few requests and call it again: used goes up. The API Keys page shows the same numbers.

#Troubleshooting

429 API_KEY_QUOTA_EXHAUSTED. The key's total quota is used up. Raise the quota or reset used quota in API Keys.

429 rate_limit_exceeded with a message like api key 1天限额已用完. A 5h, 1d or 7d window is used up. Wait until reset_at, raise the limit, or reset the window usage on the key.

429 rate_limit_exceeded with a Retry-After header. That is an account or group requests-per-minute limit, not a key budget. Wait the number of seconds in Retry-After.

403 API_KEY_EXPIRED. Set a later expiry date on the key, or create a new key.

403 ACCESS_DENIED. The caller's IP is not on the key's whitelist, or is on its blacklist. The message is deliberately vague. Check the egress IP of your server, and remember that CIDR ranges are allowed.

401 API_KEY_DISABLED. The key is switched off. Enable it in API Keys.

#Related

• Authentication for creating and sending keys.
• Limits & rate limits for account and group limits.
• Usage API reference and Errors.