Source: https://wiki.niceai.dev/guide/api/rate-limits

# 限流、超时与重试

遇到 **429、500、502、503、529** 或网络超时，可以等一会儿再重试；遇到 **400、401、403、404**，重试没有意义，要先改请求或配置。重试时用“指数退避 + 随机抖动”，并控制并发数，批量任务就能稳定跑完。

## 哪些错误该重试

| 状态码 | 是否重试 | 说明 |
| --- | --- | --- |
| 400 | 否 | 请求参数有问题，按错误信息修改 |
| 401 / 403 | 否 | 密钥、余额或分组权限问题，见 [常见错误码对照](https://wiki.niceai.dev/guide/error-codes) |
| 404 | 否 | 地址或模型名错误，见 [接口地址要不要加 /v1](https://wiki.niceai.dev/guide/v1-404) |
| 429 | 是 | 请求太频繁，或上游暂时限流。有 `retry-after` 响应头时按它等待 |
| 500 / 502 / 503 | 是 | 服务端或上游临时问题 |
| 529 | 是 | Anthropic 上游过载，等待后重试 |
| 连接超时、读取超时 | 视情况 | 非流式长请求超时后重试，可能产生重复计费，先确认是否真的需要重试 |

具体的频率和并发限制以控制台说明为准；上游模型厂商也有自己的限流，高峰期可能更容易出现 429 或 529。

## 用 SDK 自带的重试

官方 SDK 默认会对 429、5xx 和连接错误自动重试，可以按需调整次数和超时：

**-group**

```python [OpenAI Python]
from openai import OpenAI

client = OpenAI(
    base_url="https://api.niceai.dev/v1",
    api_key="sk-...",
    max_retries=4,     # 默认 2 次
    timeout=600,       # 秒；长输出、推理模型适当放宽
)
```

```js [OpenAI Node.js]
import OpenAI from 'openai'

const client = new OpenAI({
  baseURL: 'https://api.niceai.dev/v1',
  apiKey: process.env.NICEAI_API_KEY,
  maxRetries: 4,
  timeout: 600 * 1000, // 毫秒
})
```

```python [Anthropic Python]
import anthropic

client = anthropic.Anthropic(
    base_url="https://api.niceai.dev",
    api_key="sk-...",
    max_retries=4,
    timeout=600,
)
```



## 自己写重试：指数退避 + 抖动

不用 SDK、直接发 HTTP 请求时，可以参考下面的写法：

```python
import random, time, requests

RETRY_STATUS = {429, 500, 502, 503, 529}

def post_with_retry(url, headers, payload, max_retries=5):
    for attempt in range(max_retries + 1):
        try:
            r = requests.post(url, headers=headers, json=payload, timeout=600)
        except requests.RequestException:
            if attempt == max_retries:
                raise
        else:
            if r.status_code not in RETRY_STATUS or attempt == max_retries:
                return r
            retry_after = r.headers.get("retry-after")
            if retry_after and retry_after.isdigit():
                time.sleep(int(retry_after))
                continue
        # 1s、2s、4s、8s……再加一点随机数，避免大量请求同时重试
        time.sleep(min(2 ** attempt, 30) + random.random())
```

## 批量任务的并发控制

- **先小后大**：先用 1～2 个并发跑通，再逐步加大，出现 429 就回退。
- **用信号量限制并发**：Python 可用 `asyncio.Semaphore`，Node.js 可用 `p-limit` 这类库。
- **失败的单独记录**：把重试多次仍失败的请求写进文件，任务结束后再补跑，不要无限重试。
- **流式长任务**：开启 [流式输出](https://wiki.niceai.dev/guide/api/streaming) 能更早发现问题，也能避免代理因长时间无数据而断开连接。

## 超时怎么设

推理模型和长输出可能需要几分钟才能完成。客户端、反向代理、函数计算平台各自都有超时设置，取其中最短的那个生效。非流式请求建议把读取超时设到几分钟；如果平台限制较短，改用流式输出。

## 下一步

- [常见错误码对照](https://wiki.niceai.dev/guide/error-codes)
- [流式输出（SSE）](https://wiki.niceai.dev/guide/api/streaming)
