# 限流与重试

账号和每把 Key 的限制、线路满载时的返回、重试和超时的正确做法。

> https://nezhagate.com/docs/guide/rate-limits

## 账号默认不限频率

NezhaGate 默认不限制每个账号的请求频率，并发也按你的用量扩容。需要约束用量时，给每把 Key 单独设置限制。

## 每把 Key 的限制

在控制台「API Keys」页面给每把 Key 设置，留空或填 0 表示不限：

| 设置 | 作用 | 超出时 |
| --- | --- | --- |
| **每分钟请求数** | 这把 Key 每分钟最多发多少个请求。 | `429` `rate_limit_exceeded` |
| **每日预算** | 这把 Key 每天（UTC）最多花多少美元。 | `402` `insufficient_quota` |
| **总额度** | 这把 Key 一共最多花多少美元，适合交给自动化任务、防止跑飞。 | `402` `insufficient_quota` |
| **模型白名单** | 这把 Key 只能调用列出的模型。 | `403` `permission_denied` |
| **IP 白名单** | 只接受来自列出的 IP 或网段的请求。 | `403` `permission_denied` |

## 线路满载时

- 每个模型背后有多条线路，网关会自动在线路之间分配请求。某个模型的所有线路同时满载时返回 429，OpenAI 兼容接口会在 `Retry-After` 头里给出建议等待的秒数。

- 图片和视频任务不会因为满载被拒：它们先排队（`status` 是 `queued`，带排队位置和预计等待时间），轮到了自动开始。

- 限时免费的模型另有每天的调用次数上限，用完返回 429，UTC 0 点重置。

## 什么时候重试

| HTTP | 怎么办 |
| --- | --- |
| **429** | 按 `Retry-After` 头的秒数等待后重试；没有这个头就等 1、2、4 秒递增。 |
| **500 / 502 / 503 / 504** | 用指数退避重试（1、2、4、8 秒，加一点随机），一般 3–5 次就够；这类失败不扣费。 |
| **其他 4xx** | 原样重试没用：按 `error.code` 改请求（参数、模型、Key、余额）后再发。 |
| **网络错误 / 超时** | 对话可以直接重试；图片和视频先到调用日志确认任务有没有创建，再决定是否重新提交。 |

```
import random
import time
import requests

def post_with_retry(url, headers, payload, tries=5):
    for attempt in range(tries):
        r = requests.post(url, headers=headers, json=payload, timeout=600)
        if r.status_code == 429:
            time.sleep(float(r.headers.get("Retry-After", 2 ** attempt)))
            continue
        if r.status_code >= 500:
            time.sleep(2 ** attempt + random.random())     # 1, 2, 4, 8 s ... plus jitter
            continue
        return r                                           # 2xx, or a 4xx to fix in the request
    return r
```

## 超时

- 单个非流式请求最长约 10 分钟，超过会被前端网关断开（返回 524）。长回答、思考型模型请用 `stream: true`。

- 客户端的超时时间至少设到 10 分钟，否则长回答还没返回，你这边就先断开了。

- 图片和视频是异步任务，提交请求本身很快返回，不受这个限制。

## 需要更高并发

需要长期稳定的高并发，请提前在 [Telegram 交流群](https://t.me/+-erBoH9-AYY4MTM1) 或客服处说明用量，我们会按你的用量扩容。