11book / docs

文档中心

从第一次调用到生产排错,按场景找到可直接复制的配置。

文档目录 · 限流与重试

▪ rate limits

限流与重试

429 与余额不足什么时候出现、客户端该怎么写重试,以及并发调用的实用建议。

你会遇到哪些限流

  • 余额不足(insufficient_quota):账户余额或该 Key 的额度上限耗尽, 调用被拒绝且不该重试——先去充值或调高 Key 上限。
  • 请求频率限制(429 rate_limit_exceeded):短时间内请求过于集中。 这是可以重试的暂时性错误,处理方式见下节。
  • 上游容量波动(5xx / upstream error):上游渠道偶发异常。 通常短暂,按指数退避重试即可;持续失败请查看错误排查文档或联系我们。

正确的重试姿势:指数退避 + 抖动

遇到 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;
  • 更多错误码见错误排查。
The Final Page

万万不可

wan wan bu ke · never, ever

用户怕什么,我们万万不可什么。这是我们的承诺,也是名字里「万万」的意思。

01万万不可静默降级
02万万不可泄漏密钥
03万万不可糊涂收费
04万万不可暗改价格
05万万不可让额度过期
06万万不可跑路失联
BASE URLhttps://api.11book.ai/v1