OpenAI API 返回 429，别急着重试：先看是不是硬消费上限-CSDN博客

OpenAI 在 2026 年 7 月 22 日给 API 平台增加了组织级和项目级硬消费上限。达到适用上限后，受影响的 API 请求会返回 HTTP 429，错误代码为 insufficient_quota。

这个变化容易引起一种误判：监控看到 429，客户端沿用原有的指数退避，结果连续重试仍然失败。原因是 429 只说明请求无法继续，不能单靠状态码判断是请求过快，还是额度已经用完。两种故障的恢复动作不同。

先分清提醒、硬上限和平台额度

OpenAI 官方文档把消费提醒和硬消费上限分成两类控制：

控制项	到达设定金额后	是否主动中断流量
Spend alert	发送通知，API 继续运行	否
Hard spend limit	适用请求返回 `429`	是

添加硬上限后，原有提醒仍可同时使用。比较合理的配置不是只选其中一个，而是在硬上限前设置提醒，为排查异常流量或调整额度留下时间。

还有第三个容易混淆的量：OpenAI 会根据 usage tier 给组织分配获批的月度 usage limit。它与用户自行配置的 spend limit 是两套限制。即使组织和项目的硬上限都没有触发，也可能因为预付额度耗尽或获批额度用完而收到 quota 类错误。

排障时至少要同时回答这三个问题：

当前 tracked spend 是否达到组织硬上限？
请求计费所属项目是否达到项目硬上限？
组织是否还有预付额度，并且没有触及 OpenAI 批准的 usage limit？

只看一张项目用量图，不能排除组织层面的停止条件。

组织上限与项目上限会同时作用

组织硬上限覆盖该组织所有项目的 API 流量；项目硬上限只影响计费到该项目的流量。一个请求可能同时受两层限制，只要任意一层达到上限，适用请求就会返回 429 和 insufficient_quota。

假设一个组织有三个项目：

prod-search：项目上限 600 美元；
batch-report：项目上限 200 美元；
sandbox：项目上限 50 美元；
组织总上限：700 美元。

prod-search 用了 550 美元，batch-report 用了 150 美元。此时两个项目各自都没到项目上限，但组织合计已经达到 700 美元，后续请求仍会被组织上限挡住。反过来，若组织只用了 500 美元，但 sandbox 已达到 50 美元，其他项目可以继续运行，sandbox 的请求会失败。

这组数字是为了说明官方描述的双层适用关系，不是 OpenAI 的默认额度或配置建议。真正上线时，日志必须保留组织、项目和请求标识，否则看到 429 后很难知道应检查哪一层。

同样是 429，重试策略不能相同

OpenAI 的错误指南列出了两类常见 429：

Rate limit reached for requests：请求发送过快，应降低速率并按照速率限制策略重试；
You exceeded your current quota：额度耗尽或达到月度消费上限，需要检查计费和限制。

硬消费上限文档进一步给出了机器可读的 insufficient_quota。因此，客户端不要只按 HTTP 状态码分支，至少应记录响应体中的错误代码和错误信息。

下面是一个示意性的错误分类器。字段访问方式需按实际 SDK 返回对象调整：

def classify_openai_error(status_code: int, error_code: str | None, message: str):
    if status_code != 429:
        return "other"

    if error_code == "insufficient_quota":
        return "quota_or_spend_limit"

    if "rate limit" in message.lower():
        return "rate_limit"

    return "unknown_429"

处理动作也要分开：

kind = classify_openai_error(status_code, error_code, message)

if kind == "rate_limit":
    retry_with_backoff()
elif kind == "quota_or_spend_limit":
    stop_automatic_retries()
    alert_billing_owner()
else:
    preserve_error_body_for_review()