> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sub2api.ruilinlu.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 429 Too Many Requests 限速错误排查

> 429 表示请求频率超过限制，介绍如何实现指数退避重试和并发控制以避免触发限流。

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

## 常见原因

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

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

<Accordion title="并发请求过多">
  同时发起大量并行请求容易触发限流，尤其是在批量处理场景下。
</Accordion>

<Accordion title="重试循环未加退避">
  请求失败后立即重试，且重试间隔过短或没有间隔，会导致请求堆积，反而加剧 429 问题。
</Accordion>

## 解决方法

### 实现指数退避重试

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

```python theme={null}
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")
```

### 降低并发数

<Steps>
  <Step title="限制同时发起的请求数量">
    使用信号量（semaphore）或线程池控制并发。例如，将并发数控制在 5 到 10 之间。
  </Step>

  <Step title="使用队列串行处理">
    对于非紧急任务，将请求放入队列，按顺序依次处理，避免瞬时峰值。
  </Step>

  <Step title="在请求之间加入固定延迟">
    每次请求结束后主动增加一个短暂延迟（如 100-300ms），平滑请求曲线。
  </Step>
</Steps>

### 读取 Retry-After 响应头

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

```python theme={null}
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）减少长连接占用时间
* 批量任务拆分为小批次，错开执行时间

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

## 常见原因

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

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

<Accordion title="并发请求过多">
  同时发起大量并行请求容易触发限流，尤其是在批量处理场景下。
</Accordion>

<Accordion title="重试循环未加退避">
  请求失败后立即重试，且重试间隔过短或没有间隔，会导致请求堆积，反而加剧 429 问题。
</Accordion>

## 解决方法

### 实现指数退避重试

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

```python theme={null}
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")
```

### 降低并发数

<Steps>
  <Step title="限制同时发起的请求数量">
    使用信号量（semaphore）或线程池控制并发。例如，将并发数控制在 5 到 10 之间。
  </Step>

  <Step title="使用队列串行处理">
    对于非紧急任务，将请求放入队列，按顺序依次处理，避免瞬时峰值。
  </Step>

  <Step title="在请求之间加入固定延迟">
    每次请求结束后主动增加一个短暂延迟（如 100-300ms），平滑请求曲线。
  </Step>
</Steps>

### 读取 Retry-After 响应头

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

```python theme={null}
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）减少长连接占用时间
* 批量任务拆分为小批次，错开执行时间