Cherry Studio 接入 API 常见报错：401、404、429 与连接失败（2026）

Cherry Studio 的报错看着杂，实际可以先分几层：身份有没有通过、地址和模型对不对、请求有没有发出去、上游有没有限流、响应有没有在传输中被截断。按层排查，比反复重装客户端有效。

本文按 401、404、429、连接失败、流式中断和知识库报错分类，给出排查顺序、诊断命令和取证方法。界面名称和日志入口可能随版本调整，以当前版本为准。

说明：Cherry Studio 是其权利人的产品，OpenAI 是其权利人的商标。本文仅作技术排查说明，与相关厂商无隶属关系；模型与价格以站内模型价格为准。

一、先固定排查顺序

遇到报错，先保存四样东西：HTTP 状态码、响应体里的错误信息、请求时间，以及网关返回的请求 ID。没有它只能描述“大概失败过一次”；有它才能查到具体请求和上游。

然后按下面的顺序走，一次只改一个变量：

用 curl 直接请求网关，确认地址、Key 和模型是否有效。
curl 通、客户端不通，查客户端配置、代理和协议类型。
客户端和 curl 都不通，查 Key、额度、模型 ID 和网关状态。
只有长回答或知识库失败，再查流式、超时和嵌入模型。

现象	常见原因	先查哪里
401 Unauthorized	Key 错误、过期、带空格或来自其他平台	Key 与 Base URL 是否配套
404 Not Found	路径多了或少了 `/v1`	API 地址结尾
model not found	模型 ID 拼错、大小写不符或未开通	模型 ID 与价格页
429 Too Many Requests	并发、频率或额度触顶	响应头与网关用量
连接超时	代理、DNS、防火墙或证书	系统代理与网络
回答中途停止	流式连接被代理或超时切断	关闭流式对比

二、401：Key 与鉴权

401 表示服务端不认这把 Key。高频原因有：

复制时带了空格、换行或引号，实际发送的字符串不完整。
Key 属于另一个平台，却被填到了当前 Base URL 下。
Key 已删除、轮换、所属项目停用，或额度已经用完。
客户端保存失败，输入框里看着有值，请求里其实是空的。
用了 Anthropic 或 Gemini 协议去请求 OpenAI 兼容端点，鉴权头格式不匹配。

处理方法是重新粘贴 Key，确认前后没有空格；再确认 Base URL 和 Key 来自同一个平台。如果客户端支持“检查”或“测试连接”，先用它验证，再用 curl 复测。curl 能通而客户端 401，重点查客户端是否真的保存了 Key，以及协议类型有没有选错。

三、404 与 model not found

404 不一定是接口下线，更多是路径拼接错误。常见情况：

Base URL 填了完整接口地址，客户端又自动拼了一次 /chat/completions，出现重复路径。
该带 /v1 的没带，或不该带的地方多带了 /v1。
服务商类型选错，例如把 OpenAI 兼容端点配成了 Anthropic 或 Gemini。
模型 ID 大小写、日期后缀、连字符和价格页不一致。
模型存在，但当前 Key 没有开通权限。

model not found 和 404 要分开看：前者是地址通了、模型不对；后者可能连路由都没匹配上。先用 /v1/models 看网关返回哪些模型；如果列表接口不可用，就从模型价格页复制准确 ID，手动添加后重试。

四、429：限流、并发还是额度

429 至少有两种含义，处理方式完全不同：

频率或并发超限：短时间内请求太多，或同时开了多个会话、多个 Agent。
额度或余额不足：Key 所属项目没有可用额度，或达到了预算上限。

先看响应体和响应头。retry-after 表示建议等待时间；如果错误信息明确提到 quota 或 balance，就不要继续退避重试，先去控制台确认额度。只有纯限流才适合指数退避，并且要加随机抖动，避免所有客户端在同一秒重试。

Cherry Studio 里同时开多个助手、批量对比模型，很容易在不知情时放大并发。排查时先只留一个会话、一个模型，确认单请求正常后再逐步恢复。

五、连接失败、SSL 与代理

连接失败常表现为转圈后提示超时、无法连接或证书错误。Cherry Studio 通常有三种代理模式：系统代理、自定义代理和不使用代理，位置在设置的系统或通用选项中，名称以当前版本为准。

排查顺序：

确认系统代理或 VPN 正在运行，且客户端用的是“系统代理”模式。
如果填了自定义代理，确认地址和端口正确，例如 http://127.0.0.1:7890。
检查代理绕过列表，确认目标域名没有被错误排除或强制走代理。
临时切换“不使用代理”做对比，判断问题是否由代理链路引起。
公司网络做了 TLS 拦截时，确认系统证书和客户端信任链是否完整。
检查系统时间是否准确，时间偏差过大会导致证书校验失败。

常见误区是把代理地址填进 API 地址。API 地址应是模型网关的 HTTPS 地址，代理填在代理设置里，两者不要混。

六、流式输出中断

流式响应依赖长连接。常见表现是首字能出来，几秒或几十秒后停住，或只显示一部分内容。原因包括代理缓冲、空闲超时、网关超时和网络切换。

排查时先关闭流式输出，用同一条问题重试。如果非流式正常，问题基本在传输链路；重点检查代理软件、防火墙和反向代理的超时设置。反向代理要关闭响应缓冲并延长读超时，否则 SSE 会被攒着一次性返回，或在中途被切断。

还要区分“模型真的停了”和“连接被断了”。前者通常有结束标记，后者往往没有错误码，只留下半截文本。把这两种情况分开记录，后续才好判断是客户端、网关还是网络的问题。

七、知识库与 Embedding 报错

知识库报错通常不在对话接口，而在嵌入或检索环节：

只配了对话模型，没有配置可用的嵌入模型。
嵌入模型不支持当前的嵌入接口，或返回的向量维度与索引不一致。
上传的文件解析失败，例如扫描版 PDF 没有可提取文本。
换过嵌入模型但没有重建索引，旧向量和新查询不匹配。
重排或检索服务不可达，表现为检索为空或超时。

Cherry Studio 的知识库可用关键词检索，也可加嵌入模型做混合检索；切换模型时界面会触发重建。重建前先确认新模型可调用，不要同时改切分参数，否则无法判断效果变化的原因。具体入口以当前版本文档为准。

八、日志、诊断命令与取证

Cherry Studio 提供开发者模式，可在设置里打开请求调用链，用来定位模型和工具错误；入口以当前版本为准。网关侧应保留请求 ID、模型名、耗时和 Token 用量，两边时间戳对得上，才好判断问题出在哪一段。

先用 curl 做最小复现：

export ZSQH_API_KEY="sk-你的密钥"

# 1. 看地址和 Key 是否有效
curl -sS "https://ai.zhongshangqihang.com/v1/models" \
  -H "Authorization: Bearer $ZSQH_API_KEY" \
  -w "\nHTTP %{http_code}\n"

# 2. 看模型是否可调用
curl -sS "https://ai.zhongshangqihang.com/v1/chat/completions" \
  -H "Authorization: Bearer $ZSQH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"你的模型ID","messages":[{"role":"user","content":"只回复 OK"}]}' \
  -w "\nHTTP %{http_code}\n"

# 3. 单独检查 TLS 握手与证书链
openssl s_client -connect ai.zhongshangqihang.com:443 -servername ai.zhongshangqihang.com </dev/null

三条命令分别对应三个问题：Key 和地址、模型和参数、TLS 和证书。哪一步失败，就从哪一层继续查，不要同时改 Key、地址和模型。

常见问题

401 换一把 Key 就一定好吗？

不一定。换 Key 能排除 Key 本身的问题，但如果是 Base URL 与 Key 平台不匹配、协议选错，或客户端没真正保存 Key，换多少把都没用。先确认请求实际发到了哪里。

404 是模型下线了吗？

多数情况是 Base URL 路径不对或模型 ID 写错。先用 curl 请求 /v1/models，再对照模型价格确认模型标识；两步都正常，才考虑模型是否已下架。

429 一定要降低并发吗？

不一定。先看错误信息：纯限流才需要降并发和退避；额度不足时降速没有意义，要去控制台确认余额或预算。响应头里的 retry-after 可帮助判断等待时间。

为什么只有流式回答会断？

流式依赖长连接，更容易被代理缓冲、防火墙空闲超时或反向代理超时切断。关闭流式做对比；非流式正常就优先检查代理和超时，而不是反复重装客户端。

知识库报错和对话报错要分开查吗？

要。对话走聊天接口，知识库还涉及文件解析、嵌入模型、向量索引和检索服务。先确认对话模型正常，再单独检查嵌入模型是否可调用、维度是否一致、索引是否需要重建。

下一步

排查的顺序可以记成一句话：先 curl，再客户端；先状态码，再日志；一次只改一个变量。需要统一的 OpenAI 兼容入口、请求日志和用量管理，可以先注册中商起航 AI 网关，模型与价格以模型价格页为准。