429 请求过多:含义以及如何处理这一情况

在一段时间内,应用发送的请求数超过 API 允许的数量时,API 会返回 429 Too Many Requests。 该请求本身没有问题。 你发送得太频繁了,因此 API 拒绝了该请求。 如果等待并再次发送,则通常会成功。 响应通常包含一个 Retry-After 标头,告知等待的时间。 有关详细信息,请参阅 RFC 6585 第 4 节。

每个 API 以不同的方式实现速率限制。 状态代码、标头和错误正文都有所不同,因此能够正确处理一个 API 的代码可能无法正确处理下一个 API。

API Status 如何判断等待多长时间 请注意
GitHub 403 或 429 如果存在retry-after,则使用它;否则,当x-ratelimit-remaining为0时使用x-ratelimit-reset(UTC 纪元秒);其他情况下至少等待 1 分钟 一个 403 可以是速率限制或缺少权限。 读取标头以区分它们。
OpenAI 429 retry-after 某些 429 错误(如 credit_balance_exhausted)意味着重试不会有帮助。 请检查 error.code。
Anthropic 429 retry-after 支出上限 429 没有retry-after,并会持续失败,直到访问恢复。 过载的 API 返回529,而不是429。
Microsoft Graph 429 Retry-After(秒) 每个服务的限制不同,例如SharePoint和Outlook。

如何处理 429

  1. 决定是否重试。 如果错误显示配额、额度或支出限制已用尽,则重试将无济于事。 告知用户,并提醒自己。
  2. 按 API 要求的时长等待。 如果响应有Retry-After,请等待其指定的时长。 它是秒数或 HTTP 日期。 如果 API 使用速率限制标头(如 GitHub 的 x-ratelimit-reset),请等到重置时间。
  3. 否则,退避。 如果没有 API 的提示,请使用指数退避和随机抖动重试,并在几次尝试后停止。
  4. 告知用户发生的情况。 “系统正忙,5 秒后重试”也好过一个永远转个不停的加载转圈。
  5. 在下一次出现 429 错误前放慢请求速度。 如果 API 返回速率限制标头,请根据剩余次数调整请求节奏。
async function fetchWithRetry(url, options, attempts = 3) {
  for (let attempt = 1; ; attempt++) {
    const response = await fetch(url, options);
    if (response.status !== 429 || attempt === attempts) {
      return response;
    }
    const retryAfter = response.headers.get('retry-after');
    const waitMs = retryAfter
      ? (isNaN(retryAfter) ? new Date(retryAfter) - Date.now() : retryAfter * 1000)
      : 2 ** attempt * 1000 + Math.random() * 1000;
    await new Promise(resolve => setTimeout(resolve, Math.max(waitMs, 0)));
  }
}

许多 SDK 会为你重试 429。 例如,OpenAI Python SDK 默认会重试 2 次,而 .NET 标准弹性处理程序会重试 3 次并遵循 Retry-After。 当 SDK 重试次数用完时,你的代码会收到错误,因此你的代码仍需要相应的处理方案。

如何测试你的应用是否能够处理 429

开发时很少看到 429。 API 非常快,你是唯一的用户,测试数据很小。 因此,测试 429 处理的方式决定你是否在用户之前找到 bug。

Approach 你找到的内容 您错过的内容
等到投入生产 真实故障 所有情况,直到用户遇到它
在测试中模拟 API,或让编码代理编写模拟代码 重试分支是否运行 API 的实际状态代码、标头和错误正文,以及 SDK 的重试策略。 你的应用还需要一个仅用于测试的开关来访问模拟。
调用真正的 API,直到它对你进行限流 实际行为 无法按需触发 429,并且会占用实际配额
截获应用的实际流量并按需返回 429 响应 真实 URL、实际 SDK 和重试策略,以及 API 自己的 429 格式 你的应用无需做任何更改,因此它不会对你的代码进行隔离测试。 将单元测试保留用于该目的。

在您的应用中试用

Dev Proxy 会拦截你的应用向你选择的 API 发出的请求,并返回 429 响应,其中包含 API 自己的标头和错误格式,而你的应用会不断调用真正的 URL。 如果你的应用在Retry-After指定的等待时间结束前重试,它也会告知你。

下载应用调用的 API 预设,并使用它启动开发代理:

devproxy config get github-rate-limiting
devproxy --config-file "~dataFolder/configs/github-rate-limiting/.devproxy/devproxyrc.json"
API Preset
GitHub github-rate-limiting
OpenAI openai-throttling
Anthropic anthropic-throttling
Microsoft Graph(OneDrive和SharePoint:/drive、/shares、/sites) microsoft-graph-rate-limiting

然后像往常一样运行应用并观察其运行情况。 若要安装 Dev Proxy,请参阅 设置 Dev Proxy。

后续步骤

另请参阅