429 Too Many Requests 限速错误排查

当你在短时间内向 Sub2API 发送过多请求时，会收到 429 Too Many Requests 响应。这是系统的限速保护机制，目的是保障所有用户的公平使用。本文将介绍 429 的常见原因以及应对策略。

常见原因

请求频率超过限制

单账户在单位时间内可发起的请求数存在上限。当频率超过阈值时，新请求会被拒绝并返回 429。

TODO：请在后台确认实际配置后填写具体限速策略。

并发请求过多

同时发起大量并行请求容易触发限流，尤其是在批量处理场景下。

重试循环未加退避

请求失败后立即重试，且重试间隔过短或没有间隔，会导致请求堆积，反而加剧 429 问题。

解决方法

实现指数退避重试

最可靠的做法是在收到 429 后等待一段时间再重试，且每次重试时等待时间按指数增长。

import time
import random


def request_with_retry(func, max_retries=5):
    for attempt in range(max_retries):
        try:
            return func()
        except Exception as e:
            if "429" in str(e):
                wait = (2 ** attempt) + random.uniform(0, 1)
                time.sleep(wait)
            else:
                raise
    raise Exception("Max retries exceeded")

降低并发数

限制同时发起的请求数量

使用信号量（semaphore）或线程池控制并发。例如，将并发数控制在 5 到 10 之间。

使用队列串行处理

对于非紧急任务，将请求放入队列，按顺序依次处理，避免瞬时峰值。

在请求之间加入固定延迟

每次请求结束后主动增加一个短暂延迟（如 100-300ms），平滑请求曲线。

读取 Retry-After 响应头

部分 429 响应会携带 Retry-After Header，指示你应等待多少秒后再重试。你的重试逻辑应优先遵循该值：

import time

response = client.chat.completions.create(...)
if response.status_code == 429:
    retry_after = int(response.headers.get("Retry-After", 1))
    time.sleep(retry_after)

有效预防

始终为 API 调用实现带退避的重试机制，不要在报错后立即无间隔重试
生产环境中监控 429 发生率，及时调整并发策略
使用流式响应（streaming）减少长连接占用时间
批量任务拆分为小批次，错开执行时间

常见原因

请求频率超过限制

单账户在单位时间内可发起的请求数存在上限。当频率超过阈值时，新请求会被拒绝并返回 429。

TODO：请在后台确认实际配置后填写具体限速策略。

并发请求过多

同时发起大量并行请求容易触发限流，尤其是在批量处理场景下。

重试循环未加退避

请求失败后立即重试，且重试间隔过短或没有间隔，会导致请求堆积，反而加剧 429 问题。

解决方法

实现指数退避重试

最可靠的做法是在收到 429 后等待一段时间再重试，且每次重试时等待时间按指数增长。

import time
import random


def request_with_retry(func, max_retries=5):
    for attempt in range(max_retries):
        try:
            return func()
        except Exception as e:
            if "429" in str(e):
                wait = (2 ** attempt) + random.uniform(0, 1)
                time.sleep(wait)
            else:
                raise
    raise Exception("Max retries exceeded")

降低并发数

限制同时发起的请求数量

使用信号量（semaphore）或线程池控制并发。例如，将并发数控制在 5 到 10 之间。

使用队列串行处理

对于非紧急任务，将请求放入队列，按顺序依次处理，避免瞬时峰值。

在请求之间加入固定延迟

每次请求结束后主动增加一个短暂延迟（如 100-300ms），平滑请求曲线。

读取 Retry-After 响应头

部分 429 响应会携带 Retry-After Header，指示你应等待多少秒后再重试。你的重试逻辑应优先遵循该值：

import time

response = client.chat.completions.create(...)
if response.status_code == 429:
    retry_after = int(response.headers.get("Retry-After", 1))
    time.sleep(retry_after)

有效预防

始终为 API 调用实现带退避的重试机制，不要在报错后立即无间隔重试
生产环境中监控 429 发生率，及时调整并发策略
使用流式响应（streaming）减少长连接占用时间
批量任务拆分为小批次，错开执行时间

​常见原因

​解决方法

​实现指数退避重试

​降低并发数

​读取 Retry-After 响应头

​有效预防

​常见原因

​解决方法

​实现指数退避重试

​降低并发数

​读取 Retry-After 响应头

​有效预防

常见原因

解决方法

实现指数退避重试

降低并发数

读取 Retry-After 响应头

有效预防

常见原因

解决方法

实现指数退避重试

降低并发数

读取 Retry-After 响应头

有效预防