常见错误
先缩小故障范围，再调整配置。不要在错误报告里发送完整 API Key、请求正文中的隐私数据或内部堆栈。
快速诊断
- 所有客户端都失败 → 检查服务状态和本地网络。
- 只有一个客户端失败 → 检查协议、Base URL、模型 ID 和客户端版本。
- 只有一个 Key 失败 → 检查余额、额度、有效期和权限；必要时重建。
- 只有一个模型失败 → 检查模型状态和协议矩阵。
HTTP 状态码
| 状态码 | 用户侧含义 | 常见原因 | 用户操作 |
|---|---|---|---|
| 400 | 请求格式错误 | 参数、协议或模型不匹配 | 检查协议和请求体，换最小请求复现 |
| 401 | 认证失败 | Key 错误、缺失或失效 | 重新复制或创建专用 Key |
| 402 | 余额或资源异常 | 余额不足或资源异常 | 检查余额，再按控制台方式联系支持 |
| 404 | 接口或模型不存在 | 地址或模型 ID 错误 | 检查 /v1、端点和模型 ID；不同供应商的模型 ID 不要混用 |
| 429 | 限速 | 并发、RPM、TPM 或上游限制 | 降低并发，退避后重试 |
| 502 | 网关或上游异常 | 上游响应异常或协议转换失败 | 记录时间和请求 ID，用短请求复现 |
| 503 | 暂无可用资源 | 维护或资源不可用 | 查看状态页或稍后重试 |
Base URL 检查
https://api.reniuniu.win/v1.../v1/v1/responses：客户端自动拼接时又手动添加了/v1；.../responses：可能遗漏/v1；- Claude Code：
ANTHROPIC_BASE_URL填根地址，客户端再请求/v1/messages； - 404 也可能来自错误模型 ID，不要只检查 URL。
流式中断
- 把提示词缩短，关闭工具调用，确认基础请求能否完成；
- 检查本地代理、VPN、本地转发、休眠和网络切换；
- 降低并发并关闭激进自动重试；
- 记录客户端版本、协议、模型 ID、发生时间和请求 ID；
- 对长任务检查上下文是否持续增长。
客户端连接失败
完全退出客户端后重启，确保新环境变量已被进程继承。仅关闭窗口、重新打开标签或热重载配置可能保留旧进程状态。
常见故障场景
Key 有效，但请求仍失败
先确认是否只有某个模型或协议失败。Key 能通过认证不代表它一定有目标模型权限，也不代表目标协议已经验证。
客户端如果提供单独的 API Key 输入框，只填写 Key，不要手动添加 Bearer 。只有自行构造 HTTP 请求头时才添加认证方案。
提示没有可用资源
这类提示可能对应维护、资源暂不可用或请求组合不受支持。用户侧应查看服务状态、降低并发、稍后用最小请求复现，并记录请求 ID。不要尝试获取或绕过内部资源配置。
提示没有可用渠道或分组不可用（待验证）
同类平台常见 No available channel、分组名出现在报错里等形态，通常意味着 Key 的权限范围不正确、范围内暂无可用资源，或目标模型不在该 Key 的权限内。牛API是否采用类似机制尚待确认。
用户侧可做：检查 Key 的模型权限与控制台资源状态 → 换用控制台确认可用的模型做最小请求 → 换一个专用 Key 对比。无法消除时按下方清单提交信息，不要尝试猜测或绕过内部范围配置。
模型 ID 写错或混用
逐字核对控制台展示的真实模型 ID。不同供应商的相似模型名（例如带不带前缀、日期后缀）不要互相套用；客户端缓存旧模型列表时完全退出并重启。
模型列表与实际调用不一致
以控制台当前显示和牛API实测结果为准。客户端缓存模型列表时，完全退出并重启；仍失败时手动填写控制台中的真实模型 ID。
用量高于预期
暂停客户端，检查自动重试、多 Agent、长上下文、工具调用和共享 Key。按时间、Key、模型和请求 ID 对照控制台记录；筛选能力以控制台实测为准。
余额或额度正常但返回 402
同时检查账户余额、Key 总额度、可能存在的周期额度、有效期和资源状态。记录发生时间、模型、协议和请求 ID，检查是否只有单个 Key 或模型受影响，再提交人工核查。周期额度是否存在仍待控制台实测，不要反复并行重试。
提交问题时提供
- 客户端名称与版本；
- 操作系统；
- 协议、脱敏 Base URL 和模型 ID；
- 发生时间与时区；
- HTTP 状态码、请求 ID；
- 可公开的错误文本和脱敏截图；
- 最小复现步骤。
不要提供完整 Key、真实聊天内容、用户数据、订单敏感信息、后台账号、上游 URL、代理 IP 或内部堆栈。