用量封顶

什么是用量封顶

用量封顶让你能为单个 API Key 或整个账户设置每日花费上限（以 USD 计）。当超过限额，网关会立即停止受理新请求，直到 UTC 00:00 重置。适合用于：防止代码 bug 导致的失控调用、限制下游子系统预算、或控制单一团队的日支出。

• Key 级日上限：单个 API Key 当日累计花费不得超过 daily_limit。
• 账户级日上限：整个账户（所有 Key 合计）当日花费不得超过 account_daily_limit。
• 每日计数在 UTC 00:00 自动重置，时区不可配置。

Key 级日上限

为每个 API Key 单独配置每日消费上限。适合按业务/团队/环境拆分 Key，精细化管控。

账户级日上限

为整个账户（所有 Key 合计）设置每日消费上限。这是顶层兜底，即使单个 Key 未达上限，账户整体超限也会拦截。

软封顶语义

如果你需要更紧的控制，应当组合使用以下机制：

• RPM（Requests Per Minute）：限制每分钟请求数，在每个请求级别生效，兜底防止突发流量瞬间打穿日上限。
• TPM（Tokens Per Minute）：限制每分钟 token 消耗，同样在每个请求级别生效。
• 适当保留余量：将 daily_limit 设置为实际预算的 90%，为可能的并发突破预留缓冲。

超限响应

触发日上限时，Key 级返回 HTTP 429，账户级返回 HTTP 402，并在响应头注入 X-Ominigate-Usage-Cap: exceeded 标识，方便客户端快速识别并与常规计费错误区分。

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

错误响应格式

网关以标准错误结构返回额外的限额元信息（limit / used / resets_at），便于客户端展示进度条或等待重置时间。

{
  "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"
  }
}

字段说明

如何配置

在 Dashboard 中按以下步骤配置 Key 级或账户级日上限。

不配置会怎样？

日上限默认关闭，新建 Key 与新账户均不设置限额。

• 默认 daily_limit = null，表示该 Key 无日上限约束。
• 默认 account_daily_limit = null，表示整个账户无日上限约束。
• 未设限额时，请求仍受账户余额（insufficient balance 会返回 402）以及全局 RPM/TPM 速率限制约束。