限流与重试
账号和每把 Key 的限制、线路满载时的返回、重试和超时的正确做法。
账号默认不限频率
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 交流群 或客服处说明用量，我们会按你的用量扩容。
