用错误码区分 OpenAI API 限流和欠额
OpenAI API 的 HTTP 429 既可能来自请求限流,也可能来自额度不足。文章建议检查 `error.code`,进一步区分预付余额耗尽、组织支出触顶和项目支出触顶等情况。
AI 深度解读
OpenAI API 返回 429,退避一小时后同一个请求还是失败,可能是组织余额用完了,也可能是项目碰到了支出上限。原文给出的排查顺序是先读响应体里的 error.code,再决定要不要重试。单看 HTTP 状态码,这几种故障在日志里长得一样。
对接 OpenAI API 的 Node 服务,可以把这套思路用在错误处理层。限流交给退避逻辑,计费故障交给能处理额度的人,字段缺失时先看清响应体。原文提供了一段分类器,但它的缺省分支和文字建议有一处出入。
同样是 429,为什么要读 error.code
原文把 429 分成两类。一类是请求速率撞上限制,降低发送速度后可以再试。另一类是余额、支出或用量出了问题,需要处理对应的额度。计费错误可共用 error.type = insufficient_quota,这个字段能帮助归类,要定位具体原因还得往下看 error.code。
下面这段响应展示了项目支出上限如何体现在响应体里。
{
"error": {
"message": "You exceeded your current quota, please check your plan and billing details.",
"type": "insufficient_quota",
"code": "project_spend_limit_exceeded"
}
}
真正指出排查位置的是 code 那一行。按原文的解释,即使组织还有余额,某个项目使用的 Key 也可能因为项目上限收到这条错误。一个周一还能用、周二报 insufficient_quota 的 Key,可以先查额度。HTTP 401 则走另一条排查路径,先检查 Key 和认证配置。
余额、支出上限和用量上限要去哪里查
作者拆出了四处设置。组织的预付余额是实际可用来扣费的钱,用完要充值。组织支出上限是另一道限制,余额充足时也要检查。项目支出上限只影响对应项目。组织用量上限由平台分配,碰到这一项要申请提高额度,充值解决不了。
原文列了四类计费原因,还提到两种限流响应,但对应的完整错误码清单在所给文本里缺失。能直接看到的计费字符串有 credit_balance_exhausted、project_spend_limit_exceeded 和 organization_usage_limit_exceeded。分类器用 _spend_limit_exceeded 后缀处理支出上限。限流侧能看到 slow_down,也能看到它用 error.type === "rate_limit_error" 来识别另一类限流信号。
分类器能决定什么,缺字段时怎么办
作者给出的分类器把错误映射成处理动作,可以接在 Node 服务的 API 调用层。
export function triage(err) {
const e = err?.error ?? err;
const code = e?.code ?? "";
const type = e?.type ?? "";
if (code === "credit_balance_exhausted") return "top_up";
if (code.endsWith("_spend_limit_exceeded")) return "raise_or_wait_for_limit";
if (code === "organization_usage_limit_exceeded") return "request_higher_limit";
if (code === "slow_down" || type === "rate_limit_error") return "back_off";
if (!code) return "inspect_body_before_retrying";
return "unknown";
}
留意 if (!code) 那一行。原文说普通限流响应可能省略 code,并建议按限流处理。示例实现则会先看 type,若也没有 rate_limit_error 这个信号,就返回 inspect_body_before_retrying。确认是限流后,有 Retry-After 就按它给出的时间等待,同时放缓并发爬升。作者还提醒,限流可能来自组织内共享的请求量,同事跑批任务时,你自己的流量没变也可能收到 429。
我的判断
我认同把计费错误从通用 429 重试队列里拿出来。统一退避实现简单,但如果余额已经耗尽,每次重试只会多留一条失败日志。对字段缺失的响应,我更倾向于示例里的做法,先检查响应体,再决定是否退避。
原文没有给出对照实验或重试成功率。这套分流属于排障经验,能帮你缩小排查范围。四种设置的实际约束、错误码覆盖范围和恢复条件,仍要结合自己账号收到的响应与控制台核对。尤其是 raise_or_wait_for_limit 里的 wait,不能当成继续短间隔重试的依据。
能拿来做什么
- 在 Node 服务里同时记录 HTTP 状态码、
error.type和error.code,让值班的人从一条日志里判断该查余额、上限还是请求速率。 - 把已识别的计费错误从自动重试队列移出。余额耗尽通知有充值权限的人,项目或组织触顶则交给对应的额度负责人。
- 给确认属于限流的请求读取
Retry-After,同时降低批处理并发。如果自己的请求量没变,把同一组织下的其他批任务也纳入排查。