▪ rate limits
限流与重试
429 与余额不足什么时候出现、客户端该怎么写重试,以及并发调用的实用建议。
你会遇到哪些限流
- 余额不足(insufficient_quota):账户余额或该 Key 的额度上限耗尽, 调用被拒绝且不该重试——先去充值或调高 Key 上限。
- 请求频率限制(429 rate_limit_exceeded):短时间内请求过于集中。 这是可以重试的暂时性错误,处理方式见下节。
- 上游容量波动(5xx / upstream error):上游渠道偶发异常。 通常短暂,按指数退避重试即可;持续失败请查看错误排查文档或联系我们。
平台级的默认频率限额以控制台公告为准;如你的业务需要更高并发(例如批量批处理任务), 联系 [email protected] 说明场景,评估可用容量与调整方案。
正确的重试姿势:指数退避 + 抖动
遇到 429 或 5xx 时,不要立即原样重发——那只会加剧限流。 标准做法是指数退避(exponential backoff)加随机抖动(jitter): 每次重试的等待时间翻倍,并加上一点随机量避免多个客户端同步重试。
Python 重试示例
import os, random, time
from openai import APIStatusError, OpenAI
client = OpenAI(
api_key=os.environ["BOOK_API_KEY"],
base_url="https://api.11book.ai/v1",
max_retries=0,
)
def create_with_retry(messages, max_retries=3):
for attempt in range(max_retries + 1):
try:
return client.chat.completions.create(
model="YOUR_MODEL_ID",
messages=messages,
)
except APIStatusError as e:
# 只重试暂时性 HTTP 错误;余额不足不重试
if e.status_code not in (429, 500, 502, 503, 504) or "insufficient_quota" in str(e):
raise
if attempt == max_retries:
raise
# 退避:1s → 2s → 4s → 8s…,加 0~1s 抖动
wait = (2 ** attempt) + random.uniform(0, 1)
time.sleep(wait)示例关闭了 SDK 内置重试,避免两层重试叠加。只对限流和部分暂时性服务端错误重试; 参数错误、鉴权失败和余额不足会直接抛出。重试次数可按业务需求调整。
流式请求断了怎么办
stream=true 的长输出可能因网络抖动中途断开。客户端应当:
- 捕获断流异常后,把已收到的部分作为上文的末尾,续写请求补全剩余内容;
- 为断流设置最大续写次数(例如 3 次),超过则任务级报错;
- 续写属于新的请求,断流前的调用与续写都可能产生费用;请按使用记录核对,不要仅凭收到的文本估算费用。
并发建议
- 控制并发数而不是请求频率:用信号量/连接池把同时在飞的请求数 限制在经过验证的范围,并结合频率限制调整,不要为所有模型套用同一并发数。
- 批处理任务错峰:大规模离线任务放在低峰时段, 并给每批之间留间隔;突发打满容易触发限流,反而拖慢整体进度。
- 用额度上限兜底:自动化脚本务必使用设了额度上限的独立 Key, 降低循环失控的风险,并配合应用侧预算监控;并发中的请求仍需结算。
排查清单
- 偶发 429 → 检查客户端是否缺少退避重试;
- 持续 429 → 并发确实超出限额,降并发或联系调整;
- insufficient_quota → 余额或 Key 上限耗尽,充值或重建 Key;
- 更多错误码见错误排查。