故障排查

先用最小 curl 请求区分“账号/API 问题”和“客户端配置问题”：

curl -i https://coffeecatbox.cc/v1/chat/completions \
  -H "Authorization: Bearer $NEWAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "控制台中的模型名",
    "messages": [{"role": "user", "content": "回复 OK"}],
    "stream": false
  }'

curl 成功而客户端失败时，重点检查客户端的 Base URL、模型名和额外参数。

按状态码排查

400 请求参数错误

• 模型不支持某个参数；
• messages 格式错误；
• 图片、工具或 JSON 输出格式不受支持；
• 请求体不是有效 JSON。

处理：删除所有可选参数，只保留 model、messages 和 stream: false。

401 未授权

• 令牌错误、过期、禁用或已删除；
• Authorization 头缺少 Bearer ；
• 令牌中带有空格、引号或换行。

正确格式：

Authorization: Bearer sk-xxxxxxxx

403 无权限

• 令牌没有该模型权限；
• IP 白名单不匹配；
• 分组或账号权限不足；
• 请求被安全策略拒绝。

404 地址错误

最终地址应为：

https://coffeecatbox.cc/v1/chat/completions

检查是否出现 /v1/v1/，或遗漏 /v1。

429 请求过多或额度不足

• 请求频率过高；
• 并发超过限制；
• 账号余额或令牌额度不足；
• 上游模型正在限流。

降低并发并采用指数退避，不要无限快速重试。

500 / 502 / 503 上游或网关异常

先等待片刻并有限重试。持续发生时：

1. 换一个可用模型测试；
2. 在控制台查看使用日志；
3. 记录请求时间、模型、状态码和请求 ID；
4. 通过控制台公告中的方式联系管理员。

网络与证书

curl -I https://coffeecatbox.cc

如果浏览器正常而程序失败：

• 校准系统时间；
• 更新系统 CA 证书；
• 检查代理环境变量；
• 不要通过关闭 TLS 校验解决问题；
• 检查公司或校园网络是否拦截连接。

流式输出异常

内容最后一次性出现时，检查客户端或你自己的反向代理是否缓存响应。连接中途断开时，增加读取超时，并确认网络稳定。

提交问题前准备

请提供：

• 出错时间和时区；
• 请求路径，不含令牌；
• 模型名称；
• HTTP 状态码和错误消息；
• 请求 ID；
• 是否能用最小 curl 复现。

永远不要提供完整令牌

如需识别令牌，只说明令牌名称或最后几位。完整 API Key、密码和 Cookie 都不应出现在工单或聊天记录中。