限额与请求准入
ApiGo 不会只选择一个限制并忽略其余限制。一次请求必须通过所有适用检查，才会到达模型供应商。
请求检查顺序
Gateway 返回最先命中的失败原因。
| 顺序 | 检查项 | 作用范围 | 常见结果 |
|---|---|---|---|
| 1 | API Key 存在且已启用 | API Key | 401 invalid_api_key 或 403 apikey_inactive |
| 2 | Workspace 有可用资金 | Workspace | 402 insufficient_balance |
| 3 | 模型权限与输出 Token 策略允许本次请求 | API Key | 400 model_not_allowed 或 400 max_output_tokens_exceeded |
| 4 | 日、滚动 7 日与滚动 30 日消费额度尚未用尽 | API Key | 具体的 402 ..._limit_reached 错误 |
| 5 | API Key 与 Workspace 两层 RPM、TPM、并发都有容量 | 两层同时 | 带 Retry-After 的作用域/维度专用 429 |
| 6 | 供应商接受请求 | 供应商账号 | 供应商自己的响应与错误格式 |
这个顺序决定多个限制同时耗尽时你先看到哪个错误，并不表示前面的限制比后面的限制“更高级”。所有检查仍然同时有效。
Workspace 余额
余额属于 Workspace，不属于单个 API Key。同一 Workspace 的所有 Key 共用这笔资金。
- Personal Workspace 使用可用余额。
- Enterprise Workspace 可以使用现金余额与已配置授信。
- 请求开始时，Gateway 检查可用资金是否大于零。
- Gateway 不会在请求开始前按预计最终费用冻结资金。因此，已经准入的请求可能在余额越过零后才完成结算，后续新请求会被拒绝。
- 充值、授信和已结算用量会异步更新请求准入快照。余额变化后请刷新 账单并重试，不要假设它会瞬时传播。
资金不可用时，Gateway 返回 402 insufficient_balance。API Key 不会失效，恢复资金后可以继续使用。
API Key 消费额度
每个 API Key 可以设置三种互相独立的 USD 消费额度：
| 额度 | 窗口 | 恢复方式 |
|---|---|---|
| 日 | Workspace 时区的当前自然日 | 进入下一个 Workspace 本地自然日 |
| 7 日 | 当前自然日与之前 6 个 Workspace 本地自然日 | 较早日期的消费移出窗口 |
| 30 日 | 当前自然日与之前 29 个 Workspace 本地自然日 | 较早日期的消费移出窗口 |
这些窗口只累计已成功、已结算的用量。已记录消费达到或超过某项额度后，新请求会被拒绝。
检查发生在新请求运行前，而该请求的最终费用要到结算后才能确定。因此，一次请求可能让已记录消费略微超过限额。消费额度是保护线，不是预付费冻结金额。
- 未设置或
0表示该消费窗口不限。 - 多个窗口同时耗尽时，Gateway 按日、7 日、30 日的顺序检查。
- 已配置额度必须满足 日 ≤ 7 日 ≤ 30 日。
- 这些额度只作用于选中的 API Key，不是 Workspace 总预算。
RPM、TPM 与并发
运行配额用于保护容量与延迟，不会取代余额或消费额度。
| 维度 | 计数内容 | 容量如何恢复 |
|---|---|---|
| RPM | 已准入请求数 | 连续补充，不会在整分钟时刻一次性清零 |
| TPM | 准入时估算输入 Token，结束后按实际输入 + 输出用量校正 | 连续补充 |
| 并发 | 当前正在处理的请求 | 请求完成、失败或取消时释放 |
TPM 在联系供应商前必须先做准入判断，因此会使用估算值。响应结束后再按实际用量校正。已经开始的响应不会因为最终 Token 数高于估算值而被中途切断。
两层始终同时生效
每个请求都会经过两个独立层级：
- API Key 层只限制当前 Key。
- Workspace 层聚合同一 Workspace 内所有 Key 的流量，是共享硬上限。
两层都必须通过。假设 Key 配置为 100 RPM、Workspace 配置为 1,000 RPM，该 Key 最多只能使用 100 RPM；如果其他 Key 先耗尽 Workspace 共享池，即使当前 Key 未达到 100 RPM，也可能被拒绝。
不要把两层简单理解成一个静态的 min(Key, Workspace) 数字。较小配置值可以帮助理解上限，但 Workspace 层的共享用量会被其他 Key 独立改变。
配置取值优先级
| 层级 | 取值顺序 | 未设置 | 0 |
|---|---|---|---|
| API Key | 当前 Key 保存的值 | 不启用 Key 专属限制；Workspace 层仍生效 | 只关闭该维度的 Key 层 |
| Workspace | Workspace 显式值 → 对应 Workspace 类型默认值 → 不限 | 继承对应 Workspace 类型默认值 | 显式关闭该维度的 Workspace 层 |
API Key 的正数运行配额不能高于 Workspace 的正数硬上限。把 Key 层设为不限，也不能绕过正数 Workspace 限制。
新 Key 默认值
Workspace 设置中的 API Key 默认额度只是创建模板：
- 创建新 Key 时，模板值会复制到该 Key。
- 创建时显式填写的字段会覆盖模板。
- 后续修改模板不会追溯修改已有 Key。
- Workspace 运行配额仍是独立的共享生效层。
运行配额错误与重试
运行配额拒绝会返回 HTTP 429、明确的 error.code 和 Retry-After 响应头。
| 作用层 | RPM | TPM | 并发 |
|---|---|---|---|
| API Key | api_key_rpm_exceeded |
api_key_tpm_exceeded |
api_key_concurrency_exceeded |
| Workspace | workspace_rpm_exceeded |
workspace_tpm_exceeded |
workspace_concurrency_exceeded |
根据错误码判断应该降低单 Key 流量还是 Workspace 总流量。遵守 Retry-After，加入随机抖动，并限制最大重试次数。余额或消费额度的 402 如果不改变底层条件，直接重试不会恢复。
ApiGo 会跨多个 Gateway 实例协调运行容量。配置和余额异步传播，分布式协调在同步边界可能存在小范围、受控的缓冲。不要把 RPM、TPM 或并发当成精确财务截止线；成本保护请使用 API Key 消费额度。
供应商限制独立生效
ApiGo 准入后，选中的供应商仍可能执行自己的账号、模型、区域、RPM、TPM 或并发限制。供应商错误会保留原始 HTTP 状态与响应体，字段格式可能与上述 ApiGo 错误不同。
路由回退可以把符合条件的流量切换到其他已配置模型或供应商，但不能绕过 Workspace 资金、API Key 消费额度或 ApiGo 运行配额，因为这些检查发生在供应商路由之前。
常见场景
Key 显示仍有 RPM，却收到 workspace_rpm_exceeded。
其他 Key 消耗了 Workspace 共享池。请降低 Workspace 总流量或申请提高 Workspace 配额。
Key 设置为不限，仍收到 Workspace 429。
不限只关闭 API Key 层，Workspace 层仍然生效。
余额为正数，却收到 day_limit_reached。
Workspace 仍有资金，但当前 Key 已耗尽日消费额度。请提高该 Key 限额，或等待 Workspace 本地自然日切换。
刚修改配额，下一个请求仍看到旧状态。
配置会异步分发。请使用有上限的退避重试；如果持续出现，请保存 X-Request-Id 并在调用日志中排查。
