← 返回教程与交流

API 返回 429、503、529 是什么意思?限流和过载可以退避重试,余额用完和消费上限重试也没用

据各家官方报错和限流文档(2026-10-26 核对):429 不一定是请求太快,OpenAI 的 429 还包括余额用完和项目消费上限,Anthropic 档位消费封顶的 429 没有 retry-after,恢复访问前会一直失败;503(Gemini、OpenAI)和 529(Anthropic)表示服务暂时过载。Gemini 官方建议只对 429、408、5xx 这类临时错误做指数退避,不重试 400 这类客户端错误。本文给出分类表和文字版重试步骤。

API 返回 429、503、529 是什么意思?限流和过载可以退避重试,余额用完和消费上限重试也没用封面

结论先看:429 不一定是请求太快,也可能是余额用完或者到了消费上限,这两种情况重试也没用;503 和 529 表示服务暂时过载,可以等一会儿再试。Gemini 官方建议只对 429、408、5xx 这类临时错误做指数退避,不要重试 400 这类客户端错误。


说明:以下据各家官方报错页和限流页(2026-10-26 核对),我们没有做实测。

429 有哪几种原因?


OpenAI 报错页把 429 分成三种,用错误体里的 code 区分:

  • Rate limit reached for requests:请求频率超限。官方建议放慢请求节奏,响应里有 Retry-After 头时按它等待。
  • Credit balance exhausted,code 是 credit_balance_exhausted:余额用完。
  • Project spend limit reached,code 是 project_spend_limit_exceeded:项目消费上限已到。

Anthropic 的 429(rate_limit_error)也有三种来源:组织触发了限流、达到了用量档位的月度消费封顶,或者达到了 Claude Code 工作区的消费上限。

Anthropic 报错页原文:A tier spend-cap 429 has no retry-after header and keeps failing until access resumes.(档位消费封顶触发的 429 没有 retry-after 头,恢复访问前会一直失败。)

Gemini:达到按消费计算的限额时,返回 429 RESOURCE_EXHAUSTED。这类限额按滚动 10 分钟窗口计算,限流页的档位表列了 Tier 1 $10、Tier 2 $50、Tier 3 $200。官方写明是否适用要看账单历史和账户状态。

自己设的消费上限会返回什么?


Anthropic 写明:用量达到你自己为组织或工作区设置的消费上限时,返回的是 400,不是 429。只盯 429 的告警会漏掉这种情况。

503 和 529 是什么?


  • OpenAI 503:Model temporarily overloaded,code 是 server_is_overloaded,模型暂时过载。
  • Gemini 503 UNAVAILABLE:官方把它和 429 RESOURCE_EXHAUSTED 并列为「应该重试」的错误,建议指数退避。
  • Anthropic 529:overloaded_error,API 暂时过载。
  • Anthropic 500:api_error,官方建议用指数退避重试。

Anthropic 对 529 只写了「暂时过载」,本文按 Gemini 文档「5xx 是临时错误」的通用原则归入可重试。

限流是按什么算的?


  • Gemini:按项目算,不按 API key 算。每日请求数(RPD)在太平洋时间午夜重置。实验和预览模型的限额更紧。
  • Anthropic:按组织算。60 RPM 可能按每秒 1 次执行,短时间的突发请求也会触发限流。新组织可能从 Evaluation 档起步。

所以同一个 Gemini 项目多建 key 不能加额度;Anthropic 的请求要摊匀。

哪些该重试,哪些不该?


可以退避重试:

  • 普通的频率超限 429(OpenAI rate limit、Anthropic 组织限流、Gemini 限流)
  • 408、500、503、529 这类临时错误

不该自动重试,要人来处理:

  • 429 余额用完(credit_balance_exhausted)
  • 429 项目消费上限(project_spend_limit_exceeded)
  • Anthropic 档位消费封顶的 429(没有 retry-after 头)
  • 400 系列:参数错误、Invalid service_tier、Anthropic 自设消费上限

关于 service_tier:OpenAI 2026 年 10 月 21 日起可在 Platform 设置里限定项目能用的服务档位,报错页的处理办法是把 service_tier 设成项目允许的档位。

重试策略怎么写成步骤?


  1. 收到错误,先看状态码,再看错误体里的 code 或 type 字段。
  2. 是 400 系列:不重试。记日志,检查参数、service_tier 和消费上限设置。
  3. 是 429:先看 code。余额用完或项目消费上限,停止重试,通知负责人处理。Anthropic 的 429 没有 retry-after 头时,先按消费封顶排查。
  4. 是普通频率超限的 429:有 Retry-After 头就按它等待,没有就走第 6 步。
  5. 是 408、500、503、529:走第 6 步。
  6. 指数退避:第一次等约 1 秒,之后等待时间逐次加长,单次最长 60 秒,总共最多重试 4 次。这组数和 Gemini Python SDK 的默认值一致;每次加长多少、要不要加随机抖动,官方没有规定,可以按业务定。
  7. 到上限仍失败:放进延迟队列或返回明确提示,不要无限重试。
  8. 用了自带重试的 SDK:不要在外面再套一层同样的重试,否则重试次数会叠加。

还有哪些常见问题?


问:429 是不是等一会儿就好?
答:不一定。余额用完、项目消费上限、Anthropic 档位消费封顶触发的 429,等待不会让它恢复。

问:Gemini 的限额能靠多建 API key 提高吗?
答:不能。官方写明限额按项目算,不按 key 算。

问:Gemini SDK 会自动重试吗?
答:官方写明 Python SDK 会自动重试临时错误,最多 4 次,初始延迟约 1 秒,最长 60 秒。

问:为什么 Claude 用量到了上限却返回 400?
答:Anthropic 写明,达到你自己设置的组织或工作区消费上限时返回 400;达到用量档位的月度封顶才返回 429。

本文由模型港 NextRelay 按各家官方页面整理,以官方页面为准。

最后更新:2026-10-27

获取 API Key