429 时,读取错误代码和 reason,判断是哪项限制拦下了请求,然后等待 Retry-After 指定的时间,或者调整该限制。路由和回退可以减少提供商故障,但请求仍可能被提供商、工作区策略或密钥策略限流。
以上所有情况都返回
429。如果 Gateway 的配额执行暂时不可用,Gateway 会改为返回 503 并附带重试指引。
Gateway 限制
每个工作区中的每位用户都有一个每分钟请求配额,按滚动的一分钟计算。同一用户创建的 API 密钥共享这一配额。OAuth 请求计入已登录的用户,没有所有者的密钥共享一个工作区配额。 随着工作区逐渐成熟,配额会自动提高。工作区会获得它符合条件的最高一档,变更会在几分钟内生效:
免费模型默认还有每个 UTC 日 1,500 次请求的配额。它由所有免费模型共享,也由同一用户发送请求的所有工作区共享。付费模型的请求不使用这一配额。已被接受的免费请求即使随后提供商失败也会计数,同一请求内的提供商回退只计一次。
这两项限制在所有 Gateway 区域之间通用,并且可以针对特定用户和工作区提高。文件操作和任务状态轮询使用每分钟配额;管理端点不使用。
被拒绝的请求会返回
429,并附带以秒为单位的 Retry-After。请等待这么长时间后再重试。
管理 API 限制
/v1/keys、/v1/logs 和 /v1/analytics 等管理端点按凭据共享每分钟 200 个单位的配额。每个管理密钥、OAuth 令牌和控制台会话都有各自的配额,没有凭据的请求按 IP 地址共享一个配额。模型、文件、批处理和任务端点不使用该配额。
每个请求根据其工作量消耗单位:
/v1/health 和 CORS 预检请求不计费。超出配额的请求会返回 429 和 rate_limit_exceeded,reason 为 management_api_rate_limit,并附带 Retry-After: 60。计数是近似值,且这些响应不带 x-ratelimit-* 头,因此请将批量脚本分散执行,而不是一直运行到上限。
密钥限制和预算
API 密钥的每日、每周或每月请求数和支出限制,以及工作区的预算,一旦达到就会返回429 和 key_limit_exceeded。响应体中的 reason、limit_window 和 reset_at 说明是哪项限制以及它的窗口何时重置,Retry-After 给出距离重置的秒数。
当限制不会自动重置时,例如终身预算或被软阻止的密钥,不会有 Retry-After。不要重试:请提高工作区预算、提高密钥的限制,或改用其他密钥。
工作区所有者和管理员可以使用 管理密钥调用 /v1/budgets 管理预算,或在设置 → 预算中管理;该页面显示每个预算目前的支出、已用比例、本周期的预测以及重置时间。每日、每周和每月预算按 UTC 边界重置:午夜、周一 00:00 和每月 1 日。
支出提醒可以在达到这些限制之前发出警告。设为阻止的支出规则会返回 429 和 spend_rule_blocked。它是尽力而为的,会在支出超过其限制几分钟后才开始生效,因此需要精确上限时请使用密钥限制和预算。x-phaseo-spend-warning 标头表示随后可能会被阻止。
部门预算
所有者和管理员可以通过phaseo department-budgets、/v1/department-budgets API、设置 → 预算或 Terraform provider 的 phaseo_department_budget 资源管理部门预算。部门的支出统计的密钥和 OAuth 请求与部门速率限制相同。
部门用完其每日、每周或每月预算后,计入该部门的 API 密钥请求会返回 429 和 key_limit_exceeded,reason 为 department_daily_cost_budget_reached、department_weekly_cost_budget_reached 或 department_monthly_cost_budget_reached。响应体中的 department_id 和 department_name 标识该部门,reset_at 和 Retry-After 说明其预算何时重置。
- 如果预算检查暂时不可用,请求会被放行,因此部门可能在短时间内超出预算。
- 所有者和管理员会在预算用到约 80% 时收到一次移动推送,用到 100% 时再收到一次。这些提醒每 15 分钟检查一次预算,因此请求可能在 100% 提醒到达之前就已被拒绝。
速率限制策略
工作区管理员可以创建命名策略,设置requests_per_minute、tokens_per_minute 和 concurrent_requests,并将其分配给密钥、成员、部门或最终用户。可以通过 phaseo rate-limits policies 和 phaseo rate-limits assignments、/v1/rate-limits API、设置 → 速率限制,或 Terraform provider 的 phaseo_rate_limit_policy 和 phaseo_rate_limit_assignment 资源来管理它们。
哪些内容计入部门。 关联到某个部门的密钥只计入该部门。其他密钥会计入其创建者所属的每个部门,OAuth 请求会计入其用户所属的每个部门。设置了部门覆盖的成员只计入覆盖后的部门。如果要让这些密钥和 OAuth 请求只计入该成员的主部门,请在设置 → 通知中将部门归属设为主部门,或使用管理密钥在
PATCH /v1/notifications/settings 中设置 spend.department_attribution。部门预算和支出规则使用同一设置。
当多个策略同时适用时,每个策略都会计数,最先耗尽的那个会拒绝请求。策略叠加在 Gateway 限制之上。策略变更约在一分钟内生效;在控制台或通过 SCIM 进行的部门成员变更最多可能需要约五分钟。
每分钟请求数和 token 数
两者都按滚动的一分钟计算。tokens_per_minute 会在每个请求完成后统计其输入和输出 token,包括流式请求和消耗了 token 的失败请求。当过去一分钟的用量达到限制时,请求就会被拒绝,因此已经在进行中的请求可能使用量超出限制。同一请求内的提供商回退只计一次。
被拒绝的请求会返回 429 和 rate_limit_exceeded,reason 为 policy_requests_per_minute 或 policy_tokens_per_minute,并附带 policy_id、limit_scope(key、member、department、workspace 或 end_user)以及以秒为单位的 Retry-After。
策略覆盖的请求的响应会携带限制最严格的那项的标头:
被拒绝的请求只携带拒绝它的那项限制的标头。计数在后台进行,因此
remaining 是近似值,并且 token 标头尚未包含当前请求自身的用量。
并发请求
concurrent_requests 限制同时进行中的请求数量。请求从被接受起占用一个槽位,直到其响应完全发送完毕(包括整个流式响应);请求内的提供商和模型回退共享这个槽位。当所有槽位都被占用时,请求会被拒绝,reason 为 policy_concurrent_requests,并附带 Retry-After: 1。
检查并发限制需要等待策略的计数器,这会增加少量延迟。如果某个槽位的释放丢失,它会在 15 分钟后自动释放。批处理和实时会话不受限制,视频生成只在启动它的请求进行期间占用槽位。
严格策略
默认情况下,策略采用失败放行:如果无法检查其限制,请求会被放行。设置fail_closed 可将其设为严格策略。严格策略会在发送请求之前(而不是在后台)检查请求数和 token 限制,这样更精确,但会增加延迟。如果两秒内无法完成检查,请求会被拒绝,reason 为 policy_unavailable。
并发拒绝和 policy_unavailable 拒绝不携带 x-ratelimit-* 标头。
提供商限制
BYOK 请求使用你自己提供商账户的限制。托管请求使用共享的提供商容量,这并不是分配给你工作区的配额。 当提供商发送Retry-After 时,Phaseo 会在校验后转发它。BYOK 响应还可能包含 X-Phaseo-Upstream-RateLimit-* 标头;托管请求会省略这些标头,因为它们描述的是共享容量。其他上游标头不会转发。提供商的 429 代码请参阅错误代码。
处理被限流的请求
- 读取错误代码,区分临时限流与需要更改配置的限制、预算或策略。
- 如果存在
Retry-After,请遵守它。它可以是秒数或 HTTP 日期;在安排重试之前先校验它。 - 否则,使用带抖动和最大延迟的指数退避。
- 用尝试次数和总体截止时间限制重试。取消已放弃的工作,并在重试前释放每个失败响应的正文。
- 如果限流持续,请降低并发。
429 比率,并在请求日志中查看回退频率。将它们与你的路由设置进行比较;对于 BYOK 流量,还要与你提供商账户的配额进行比较。护栏控制哪些密钥可以使用哪些模型和提供商。