在一段时间内,应用发送的请求数超过 API 允许的数量时,API 会返回 429 Too Many Requests。 该请求本身没有问题。 你发送得太频繁了,因此 API 拒绝了该请求。 如果等待并再次发送,则通常会成功。 响应通常包含一个 Retry-After 标头,告知等待的时间。 有关详细信息,请参阅 RFC 6585 第 4 节。
常用 API 中的 429 是什么样
每个 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
- 决定是否重试。 如果错误显示配额、额度或支出限制已用尽,则重试将无济于事。 告知用户,并提醒自己。
- 按 API 要求的时长等待。 如果响应有
Retry-After,请等待其指定的时长。 它是秒数或 HTTP 日期。 如果 API 使用速率限制标头(如 GitHub 的x-ratelimit-reset),请等到重置时间。 - 否则,退避。 如果没有 API 的提示,请使用指数退避和随机抖动重试,并在几次尝试后停止。
- 告知用户发生的情况。 “系统正忙,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。