外观
常见问题排查
用着用着报错或者没反应？先看看是不是下面这些常见情况。90% 的问题都出在配置上，按本文一一对照即可解决。
错误 1：401 Unauthorized（认证失败）
报错样子： 401 Unauthorized / Invalid API Key / Authentication failed
原因： API Key 不对。
怎么办：
- 检查 Key 是否复制完整，首尾有没有多余的空格
- 检查 Key 是不是
sk-开头那一串完整字符串 - 登录管理页面，确认这个 Key 还在、没有被删除或禁用
- 如果不确定，重新创建一个 Key 试试
错误 2：404 Not Found（找不到接口）
报错样子： 404 Not Found / The requested URL was not found
原因： API 地址（Base URL）填错了，多半是 /v1 重复或缺失。
正确的地址应该是：
https://api.example.com/v1常见错误：
| 错误填法 | 问题 |
|---|---|
https://api.example.com/v1/v1 | 重复了 /v1 |
域名末尾少了 /v1 | 客户端没有自动追加 |
末尾多了 / | 部分客户端会拼成 //chat/completions |
TIP
如果你的客户端会自动在地址后面加 /v1，那你只填域名部分（不带 /v1）。如果客户端不会自动追加，就填完整带 /v1 的地址。不确定的话，两种都试一下。
错误 3：模型不存在 / Model not found
报错样子： The model 'xxx' does not exist / model not found
原因： 你填的模型名称在卡皮巴拉这边没有，或者拼错了。
怎么办：
- 登录管理页面查看支持的模型列表
- 完全照抄模型名称，包括大小写、横杠、数字
- 不要用其他平台听说的模型名（不同平台命名可能不同）
常见拼写错误举例：
- ❌
gpt4→ ✅gpt-4 - ❌
Claude-3.5-Sonnet→ ✅claude-3-5-sonnet-20241022 - ❌
gemini2.0→ ✅gemini-2.0-flash-exp
错误 4：请求很久没反应 / 一直转圈
原因可能有几个：
| 现象 | 可能原因 | 处理方法 |
|---|---|---|
| 一直转圈，最后超时 | 网络不通 | 检查电脑能否打开服务地址 |
| 输出一段后突然中断 | 模型本身的限制 | 重试，或换个模型 |
| 完全没流式输出，等很久后一次性出现 | 客户端没开启流式响应 | 在客户端设置里开启「流式输出」 |
错误 5：余额不足 / Quota exceeded
报错样子： Insufficient quota / 余额不足 / 429 Too Many Requests
原因： 你的账户余额用完了，或者达到了使用频率上限。
怎么办：
- 登录管理页面查看剩余余额
- 如有需要，联系卖家充值
- 如果是频率限制，稍等片刻再试
错误 6：连接被拒绝 / 无法访问
报错样子： Connection refused / ECONNREFUSED / Network Error
怎么办：
- 用浏览器打开服务地址
https://api.example.com/v1/models，看是否能访问 - 检查电脑网络是否正常
- 如果你开了 VPN/代理，尝试关闭后再试（有些代理会拦截 API 请求）
- 如果浏览器也打不开，可能是服务暂时不可用，联系客服
还是不行？
如果以上方法都没解决，提供以下信息联系客服可以更快定位问题：
- ✅ 用的是什么客户端（Cherry Studio / Chatbox / 其他）
- ✅ 完整的报错信息（截图或文字）
- ✅ 客户端里填写的 API 地址和模型名（Key 不要发）
- ✅ 大概什么时候开始出现的问题