Usage Caps

Set daily spending limits on API keys and accounts to prevent runaway costs.

Usage Caps

What are usage caps?

Usage caps let you set daily spending limits (in USD) on individual API keys or across your entire account. When a cap is exceeded, the gateway immediately stops accepting new requests until the next UTC 00:00 reset. Typical uses: protect against runaway calls from buggy code, enforce per-integration budgets, or contain a team's daily spend.

  • Key-level daily limit: a single API key's cumulative daily spend is bounded by daily_limit.
  • Account-level daily limit: your account's total daily spend (across all keys) is bounded by account_daily_limit.
  • Counters reset automatically at UTC 00:00 every day; the timezone is not configurable.

Key-level daily limit

Configure a per-key daily spending cap. Useful when you split keys by business unit, team, or environment and want fine-grained control.

daily_limitUSD decimal; null means unlimited

When the key's cumulative daily spend reaches daily_limit, new requests return HTTP 429 with code key_daily_limit.

Account-level daily limit

Set a daily spending cap across your entire account (the sum across all keys). This is a top-level safety net: even if no single key has hit its limit, the account cap still blocks requests once the total is exceeded.

account_daily_limitUSD decimal; null means unlimited

When your account's cumulative daily spend reaches account_daily_limit, every key returns HTTP 402 with code account_daily_limit.

Soft cap semantics

Important: daily limits are soft, not hard quotas

Daily limits are enforced via a read-compare-write check at request ingress, which leaves a small TOCTOU window. With bursts of concurrent requests your total spend may slightly overshoot the configured daily_limit. Do not rely on daily limits as a strict budget wall.

If you need tighter control, combine the daily cap with these per-request mechanisms:

  • RPM (requests per minute): enforced per request, protecting against bursty traffic blowing past the daily limit.
  • TPM (tokens per minute): likewise enforced per request to bound token throughput.
  • Leave headroom: set daily_limit to ~90% of your actual budget so the TOCTOU overshoot stays within your intended ceiling.

Exceeded response

When a daily cap is exceeded, the gateway returns HTTP 429 for key-level caps and HTTP 402 for account-level caps, both with an X-Ominigate-Usage-Cap: exceeded response header so clients can distinguish them quickly from other billing errors.

HTTP/1.1 429 Too Many Requests
X-Ominigate-Usage-Cap: exceeded
Content-Type: application/json

Error response format

The gateway returns extra metadata (limit / used / resets_at) alongside the standard error envelope, so clients can render a progress bar or display a retry-after timestamp.

{
  "error": {
    "type": "usage_cap_exceeded",
    "code": "key_daily_limit",
    "message": "API Key has exceeded its daily spending limit.",
    "limit": "10.00",
    "used": "10.42",
    "resets_at": "2026-04-15T00:00:00Z"
  }
}

Field reference

typeusage_cap_exceeded

Error family. Always usage_cap_exceeded for daily cap errors.

codekey_daily_limit | account_daily_limit

Specific error code. key_daily_limit / key_monthly_limit for the key caps, account_daily_limit for the account cap.

limitstring (decimal)

Configured daily limit in USD (decimal string).

usedstring (decimal)

Cumulative spend today in USD (decimal string). May slightly exceed limit due to the concurrency window.

resets_atstring (RFC3339 UTC)

Next counter reset in UTC (RFC3339). Always tomorrow at UTC 00:00:00.

How to configure

Configure key-level or account-level daily limits from the Dashboard using either of the following.

Key level: API Keys page

Open Dashboard > API Keys, click Edit limits on the target key, and enter a daily amount. Leave it blank to remove the key-level cap.

Go to API Keys→

Account level: Billing page

Open Dashboard > Billing and set the account daily limit. Leaving it blank (or null) removes the account cap; spend will then be bounded only by your balance and global rate limits.

Go to Billing→

Manually reset today's spend

The Dashboard provides a Reset today button that immediately zeroes out today's cumulative spend for both key-level and account-level counters. Note: this only resets the counter. It is not a refund — the money already spent is not returned to your balance.

What if I don't configure caps?

Caps are off by default. New keys and new accounts start with no daily limit.

  • daily_limit = null (default): the key has no daily cap.
  • account_daily_limit = null (default): the account has no daily cap.
  • Without caps, requests are still bounded by your account balance (insufficient balance returns 402) and the global RPM/TPM rate limits.

Need help?

Reach out at support@ominigate.ai for any questions or issues.