跳到主要内容

错误、速率限制与可靠性

进阶
What you'll learn
  • 读懂 HTTP 错误对照表，明确哪些状态应重试、哪些应修复
  • 用带上限的指数退避加抖动重试瞬时错误
  • 通过 retry-after、平滑流量、批处理和更便宜的模型来应对速率限制
  • 让你的代码隔离于模型弃用与迁移

生产代码与一个网络服务通信，因此它必须预期失败。在这里多一点结构，就是脆弱的集成与可靠的集成之间的区别。

错误对照表​

你将要处理的典型 HTTP 状态：

状态含义应对方式
400无效请求修正负载；不要原样重试
401API 密钥错误/缺失检查凭据
403无权限检查访问权限
429触发速率限制退避并重试（遵守 retry-after）
500/529服务端错误 / 过载带退避地重试
Pro tip
  • 各 SDK 将这些以类型化异常的形式暴露出来，因此你可以干净地分支处理，而无需解析字符串。

带退避的重试​

对于瞬时错误（429、5xx），使用 指数退避 + 抖动 进行重试，并设上限：

import time, random
for attempt in range(5):
    try:
        return client.messages.create(...)
    except (RateLimitError, APIStatusError) as e:
        if attempt == 4 or not should_retry(e):
            raise
        time.sleep(min(2 ** attempt + random.random(), 30))
Watch out
  • 许多 SDK 会自动重试瞬时错误——在添加自己的重试逻辑之前，先了解你所用客户端的默认行为，否则你可能会叠加重试。

速率限制​

限制按账户/层级（每分钟的请求数和 token 数）施加。当你触发某个限制时，会收到带有时间提示的 429。把请求量控制在上限之下的策略：

Guided walkthrough1 of 4
  1. 收到 429 时，读取响应中的时间提示，并在重试前等待相应时长。

参见 选择模型，为高并发步骤挑选合适的模型。

模型迁移​

模型 ID 带日期/版本，并会被弃用。为自己留好缓冲：

Key takeaways
  • 400/401/403 是你这边的问题——修正请求或凭据，不要盲目重试。429 和 500/529 才是可重试的。
  • 用带上限的指数退避加抖动重试瞬时错误（例如 min(2 ** attempt + random(), 30)）。
  • 遇到 429 时：遵守 retry-after、平滑突发流量、批处理离线工作，并把高并发步骤路由到更便宜的模型。
  • 从配置中读取模型 ID，关注弃用，迁移模型时重新运行评测。

自我检测

0/4
  1. 你收到一个 400 无效请求。你应该怎么做？
  2. 哪些状态是你应当带退避重试的？
  3. 为什么要给指数退避加上抖动？
  4. 以下哪一项不是建议的速率限制策略？

下一步​