HTTP 429 错误

详细解释

HTTP 429 Too Many Requests 是你接入大模型 API 后一定会遇到的状态码。它不是”服务器挂了”，而是服务商礼貌地告诉你：先缓一缓。

在响应体里，主流厂商会附上：

• retry-after / x-ratelimit-reset-requests：还要等几秒
• 错误类型码（如 Anthropic 的 rate_limit_error、Google 的 RESOURCE_EXHAUSTED）
• 是哪条轴超限（RPM / TPM / 并发 / 消费额）

典型 429 响应示例

HTTP/1.1 429 Too Many Requests
retry-after: 12
x-ratelimit-limit-requests: 1000
x-ratelimit-remaining-requests: 0
content-type: application/json

{
  "error": {
    "type": "rate_limit_error",
    "message": "Number of request tokens has exceeded your per-model limit",
    "retry_after_ms": 12000
  }
}

千万不要做的事

❌ 429 后立刻全速重试：这会触发”正反馈螺旋”——每一个重试请求都在继续消耗你的配额，导致你被限速更久，甚至被临时封号。

✅ 正确做法：

1. 读取 retry-after 头，严格 sleep 对应秒数；
2. 加上指数退避（每次失败把等待时间 × 2）；
3. 加入随机抖动（Jitter），避免所有请求同时”喊开始”。

唯元智创（Weimeta）SDK 内置了可配置的指数退避 + 抖动 + 重试次数上限，不需要你自己手写。

常见问题