配额管理
功能简介
配额管理用于控制和限制 API 调用的使用量，确保资源的合理分配。通过设置周期性配额，可以预防意外的高额消费。
上线时间： 2026年4月10日
周期性配额
功能说明
该版本先仅支持 cost 配额（按费用维度的控制）。
配额配置
在控制台中新增"配额"模块，创建配额规则时可进行以下配置：
- 配额数值：设定本周期内的最大消费额度
- 重置周期：选择配额的重置周期
- 日：每天重置一次
- 周：每周重置一次
- 月：每月重置一次
- 作用目标：选择规则应用的范围
- API Key：对特定或所有 API Key 生效（可勾选"全部"对所有 API Key 生效）
- Project：对特定或所有 Project 生效（可勾选"全部"对所有 Project 生效）
- 组织账号：对当前组织账号整体生效
配額规则示例
建议的配额规则设置方式：
第一步：创建 3 条全局规则
规则1：全部 API Key，周期为日，配额为 100
规则2：全部 Project，周期为周，配额为 500
规则3：组织账号，周期为月，配额为 5000
第二步：针对特定需求，创建覆盖规则
规则4：特定 API Key（如"VIP 应用"），周期为日，配额为 1000
规则5：特定 Project（如"正式环境"），周期为月，配额为 10000提示：用量超过配额限制后，可通过提高配额数值让 API 调用恢复使用。
配额管理界面
图1：配额管理 - 配额规则列表
图2：配额管理 - 配额控制
API 调用限制
限制规则
当 API 调用时，系统会进行以下检测：
- 检测当前 API Key 的用量：是否已达到或超过相关规则的配额限制
- 多规则判定：如果触发任意一条规则的限制（包括所属 Project 的规则、组织账号的规则等），则禁止本次 API 调用
- 返回状态码：被禁止的请求将返回 429 状态码
限制场景示例
场景一：单个 API Key 超限
配额规则：API Key "key-001" 的日配额为 100
情况：
- 当前 API Key 已消费 99，本次请求预计消费 2
- 触发限制条件（99 + 2 > 100）
- API 调用被禁止，返回 429
恢复方法：提高该 API Key 的日配额至 102 或以上场景二：多层级嵌套限制
配额规则：
规则A：API Key "key-002" 的周配额为 1000
规则B：Project "projectA" 的周配额为 500（key-002 属于 projectA）
规则C：组织账号的周配额为 2000
当前消费统计：
- API Key level：已消费 800（规则A）
- Project level：已消费 480（规则B）
- Organization level：已消费 1800（规则C）
结果：
- 规则A：未超限（800 < 1000）✓
- 规则B：已超限（480 + 请求 > 500）✗
- 规则C：未超限（1800 + 请求可能 < 2000）
本次 API 调用被禁止（规则B触发），返回 429监控和调试
常见问题
Q: 如何区分不同级别的配额？
A： 系统支持三个级别的配额：
- API Key 级别：最细粒度，针对单个 API Key 的限制
- Project 级别：针对项目层级的限制，同一项目下的所有 API Key 共享
- 组织级别：最粗粒度，整个组织账号的总体限制
Q: 多个规则同时生效时，哪一个优先？
A： 系统采用"最严格优先"的判定逻辑。只要触发了任意一条规则的配额限制，API 调用就会被禁止。
Q: 超限后如何恢复？
A： 可通过以下方式恢复：
- 提高配额数值：编辑对应规则，增加配额上限
- 等待周期重置：配额在周期结束后会自动重置（配额使用量清零）
- 创建例外规则：针对特定 API Key 或 Project 创建更高配额的规则
Q: 429 错误的具体含义是什么？
A： 429 状态码表示"请求过于频繁"或在此场景下表示配额限制触发。检查方式：
- 查看最近的 API Key 消费记录
- 确认是否有配额规则被触发
- 查看具体触发的规则级别（API Key / Project / Organization）