Cherry Studio 接入多个模型 API 后，错误码归一化查看在哪些入口、按什么规则映射？

Cherry Studio 的 API 错误码归一化查看，是把不同提供商返回的 HTTP 状态码与 JSON 错误体统一归到认证、限流、参数、模型、服务端五类，并在同一个报错位置同时给出归一化结论和原始响应；它只对经由客户端自身请求链路发出的调用生效，用外部脚本直接请求接口时看不到这套结果。理解这个边界很重要，它决定了你什么时候该看界面提示，什么时候必须回到原始请求。 归一化之所以必要，是因为各家返回结构本来就不同。一类把错误信息放在顶层 error 对象里，带 message、type、code 三个字段；一类把错误类型放在顶层 type，内层 error 再放 type 和 message；还有一类用数字 code 配 status 字符串。Cherry Studio 抽取的是这些结构里共有的语义位而不是字段名，所以界面提示不会随提供商切换而变形。 判断一个报错，先分层，再看具体码。传输层表现为超时、连接被拒、TLS 握手失败，通常没有状态码；HTTP 状态层是 401、403、404、429、5xx；业务码层是状态码之外 body 里的额外标识，比如余额不足、上下文超长、模型不存在。把这三层压在同一屏，才不会只看到一句 message 就去乱改配置。 最直接的查看入口是对话窗口里的报错提示。请求失败后，消息位置会出现错误说明和重试按钮，归一化后的摘要一般能指出方向：是密钥问题、限流问题还是参数问题。需要精确定位时，把错误详情或原始返回复制出来，里面保留了提供商的原始响应体。这一步适合处理单次失败，不适合判断是否为长期配置问题。 模型服务设置里的连通性检测，是配置阶段最有效的归一化查看方式。新增或修改一个提供商后先做可用性测试，能够提前暴露密钥失效、接口地址写错、余额不足、模型名不存在这几类问题，而它们在真实对话里常常被包装成同一句通用失败。检测通过再回对话验证，可以少走不少弯路。 桌面端还能借助运行环境自带的开发者工具查看原始请求。打开网络面板，可以看到实际发出的请求地址、请求头和响应体，这是唯一能同时看到请求与响应两侧信息的位置。当归一化摘要与你的预期不符时，应当以网络面板里的原始响应为准，因为摘要经过了抽取和映射，原始响应才是事实。 部分版本会在本地保存运行记录，具体是否提供以及存放路径，以当前客户端的数据目录设置为准。如果能在其中按时间顺序找到请求记录，排查偶发失败会方便很多，尤其是那种重试一次就成功、在对话里已经看不到现象的问题。没有日志入口时，用网络面板配合最小请求复现，同样能完成定位。 常见错误码的归一化处理，可以按固定顺序记忆。401 与 403 指向密钥无效或权限不足，404 多数是接口地址或模型名不对，429 是限流或并发超限，400 且带上下文超长语义是输入超过该模型窗口，5xx 优先怀疑上游服务状态。记住这几类，现场排查就能先排除配置问题，再看服务状态。 经由中转或聚合层调用时，错误码可能被改写一次。中转服务通常会把识别到的上游错误重新封装成统一格式，此时界面显示的是映射后的码，未必等于上游原始码。区分办法是对比响应里的标识字段，若缺少上游原始信息，就只能从状态码和文案反推；这类场景下归一化解决的是分类问题，不是溯源问题。 长期使用多个提供商，建议自己维护一张错误码映射表。表里至少记录提供商、原始状态码、原始 code、归一化分类、处理动作五列，遇到重复报错直接查表，比每次翻原始响应快得多。排查顺序固定为先认证、再参数、后服务端，最后才考虑网络环境，这个顺序能覆盖大多数失败场景。 流式响应和超时需要单独处理。流式输出中途断开时，错误往往不在最终 body 里，而要回到事件流中查看，普通的错误码查看方式在这里不适用；连接超时也可能在客户端侧就被直接判定为失败，压根没有返回任何状态码。这两类情况应结合网络面板的时序和请求参数逐项核对，而不是只看一句错误提示。 归一化查看只能统一展示形式，不能统一语义。同样是 429，在不同提供商的计费与并发策略下含义并不相同；同样是 401，也可能来自密钥被禁用、额度耗尽或权限范围不足。遇到这类同码不同因的情况，应回到原始响应和处理动作做二次确认，界面上的那一句话只作为分类入口使用。