错误与状态码
调用出错时，先看状态码和返回的错误文案——它们直接告诉你问题在哪。下表按「现象 → 原因 → 解决办法」整理了最常见的报错。
快速对照
| 状态码 | 你可能看到 | 原因 | 解决办法 | 要不要重试 |
|---|---|---|---|---|
| 401 | 无效的令牌 / 未提供令牌 | 没带令牌、复制不全、已停用 | 检查 Authorization: Bearer sk-...，重新完整复制令牌 | 不要 |
| 403 | 该令牌额度已用尽 | 这个令牌自身的限额用完了，给账户充值不能解除 | 到「令牌管理」编辑该令牌调高金额或改为无限额度（编辑需开启高级模式），或新建一个足额令牌更换 | 不要 |
| 403 | 用户额度不足, 剩余额度: … | 账户余额不够 | 去「钱包管理」充值 | 不要 |
| 403 或 404 | 该令牌无权访问模型 … / 模型不存在 | 模型名写错，或令牌/分组不可见该模型 | 核对模型 ID（从模型广场复制）；令牌限制了模型时，编辑该令牌放开（需开启高级模式） | 不要 |
| 403 | 无权访问 … 分组 / 分组 … 已被弃用 | 令牌选的分组不可用 | 新建一个令牌并选择可用分组（如 default），旧令牌可停用 | 不要 |
| 403 | 您的 IP 不在令牌允许访问的列表中 | 令牌配了 IP 限制 | 到「令牌管理」检查该令牌的 IP 限制，或换回允许的网络 | 不要 |
| 404 | Invalid URL | Base URL 填错 | SDK 和标准 OpenAI 客户端填 https://api.biyuan.ai/v1；会自行拼接 /v1 的客户端（如 Cherry Studio、NextChat、Claude Code）填不带 /v1 的地址 | 不要 |
| 429 | 您已达到请求数限制:…分钟内最多请求…次 | 触发频率限制 | 先等几秒再重试，还不行就把每次的等待时间翻倍 | 可以，有限次 |
| 5xx | 网关或上游异常、超时 | 上游或链路波动 | 退避重试，或换更稳的模型/分组 | 可以，有限次 |
额度不足是 403，不是 402/429。额度类报错的返回里通常还带有充值和令牌页面的链接。
按状态码看
401 未认证
令牌本身的问题。逐项检查：
- 请求头是不是
Authorization: Bearer sk-...（少了Bearer也会 401） - 令牌前后有没有多余空格、是否复制完整
- 令牌是否已过期或停用
- 客户端是不是还缓存着旧令牌
先跑 GET /v1/models 做最小验证。注意：401 是令牌本身的问题，而操练场用的是网页登录身份、不经过令牌，验证不了它——不想用命令行的话，在聊天客户端里重新完整粘贴一次令牌再试。
403 无权限 / 额度不足
请求到了，但被规则拦下。403 先看错误文案：额度类（该令牌额度已用尽/用户额度不足）先处理额度；策略类再查分组、模型权限或来源（IP）限制。
- 「该令牌额度已用尽」说明是这个令牌自身的限额用完了，给账户充值不能解除；到「令牌管理」编辑该令牌，调高金额或改为无限额度（编辑需开启高级模式），或新建一个足额令牌并更换使用。
- 「用户额度不足」才是账户余额不够，去「钱包管理」充值。
- 「无权访问模型」：模型名写错，或令牌/分组不可见该模型（同样的问题也可能返回 404，见下一节）。
- 「无权访问分组」/「分组已被弃用」：如需换分组，新建一个令牌并选择目标分组，旧令牌可停用。
- 「IP 不在允许列表」：令牌配了来源（IP）限制，到「令牌管理」检查，或换回允许的网络。
这类问题重试没用，得改配置。
404 地址或模型错误
先分清是地址错还是模型错：
- 地址错：SDK 和标准 OpenAI 客户端填
https://api.biyuan.ai/v1；会自行拼接/v1的客户端（如 Cherry Studio、NextChat、Claude Code）按各自接入页填不带/v1的地址。地址填错时常见的报错是Invalid URL。 - 模型错：模型名写错，或令牌/分组不可见该模型时，可能返回 403 或 404，以返回的错误文案为准。先核对模型 ID——从模型广场复制；想确认当前令牌实际可用的模型，调用
GET /v1/models（令牌设置了模型限制时，以这个返回为准）。
429 频率限制
触发了请求频率上限。先等几秒再重试；还不行就把每次的等待时间翻倍（这个做法叫「指数退避」），并设一个最大重试次数，别让多个客户端同时无限重试。用聊天客户端的话：等一两分钟再发，或减少同时进行的对话。如果长期 429，考虑减少同时发出的请求（降低并发）。
5xx 上游或链路问题
更像链路波动，不是你的参数错。可以先缩短请求、减少上下文，确认是否只在某个模型或分组下出现，再决定退避重试还是换模型。
一个例外：503 且错误文案为 model_not_found，表示该模型当前没有可用渠道，重试无效。先核对模型名，再确认当前令牌/分组开放了该模型——调用 GET /v1/models，或到操练场试同一个模型。
要不要重试
- 不要重试：
400、401、403、404——配置或参数问题，重试也不会变。 - 可以有限重试：
429、502、503、504，以及少量可恢复的500——用退避 + 最大次数。例外是 503 报model_not_found，重试无效，见上一节。
第三方客户端的排查
用 Cursor、Cherry Studio、Open WebUI 等客户端时，报错常常不是平台不可用，而是客户端行为：
- 缓存了旧的模型列表
- 默认切到了不可用的模型
- 自动附带了当前模型不支持的参数
- 网络波动时自动重试
所以先检查：客户端当前选中的模型、Base URL 是否正确、API Key 是不是当前令牌、是否开了自动重试或模型缓存。
最短排查路径
- 先看状态码和返回文案。
- 判断是配置类（4xx）还是链路类（5xx）。
- 跑
GET /v1/models验证令牌和连通性。 - 再发一条最小
chat/completions。 - 确认是否只在某个模型、某个客户端或某个分组下复现。
不想用命令行的话：登录控制台，在操练场选同一个模型发一句话。能收到回复，说明账号、额度和模型都正常，问题多半出在客户端配置或令牌本身——操练场用的是网页登录身份，验证不了具体某个令牌。