跳到主要内容

错误、速率限制与可靠性

进阶

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

错误对照表​

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

状态含义应对方式
400无效请求修正负载；不要原样重试
401API 密钥错误/缺失检查凭据
403无权限检查访问权限
429触发速率限制退避并重试（遵守 retry-after）
500/529服务端错误 / 过载带退避地重试

各 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))

（许多 SDK 会自动重试瞬时错误——在添加自己的重试逻辑之前，先了解你所用客户端的默认行为。）

速率限制​

限制按账户/层级（每分钟的请求数和 token 数）施加。当你触发某个限制时，会收到带有时间提示的 429。应对策略：遵守 retry-after、平滑突发流量、对离线工作进行 批处理，并在高并发步骤上使用更便宜的模型（选择模型）。

模型迁移​

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

下一步​