Cherry Studio 接入多个模型厂商后,API 错误码怎么归一化查看,才能分清鉴权、限流和上游故障?
把 HTTP 状态码、厂商返回的 error.type / error.code 和原始 message 拆成三层,再按鉴权与权限、限流配额、参数与上下文超限、模型或路径不存在、上游 5xx、网络超时六类归并,就能在 Cherry Studio 的请求日志里用统一口径看错误;流式响应中的 error 事件必须一起纳入,否则会被 200 状态掩盖。
Cherry Studio 里的 API 错误码归一化查看,本质是把 HTTP 状态码、厂商自有错误类型和上游原始 message 这三层信息拆开,映射成鉴权与权限、限流配额、参数与上下文超限、模型或路径不存在、上游 5xx、网络超时六类之后再读;它适用于通过 OpenAI 兼容接口接入多个模型厂商的场景,不适用于厂商返回加密或私有二进制错误体的协议。
不做归一化的直接后果是同一个问题在不同厂商下看起来像三种不同故障。OpenAI 兼容风格把错误放在 error.message、error.type、error.code 三个字段里,Anthropic 主要用 error.type 表达类别,Google Gemini 用 error.status 加数字 code 表达,一条「模型名写错」的提示在界面上可能显示成 404,也可能显示成 400 invalid model。只盯着弹窗里那串英文,最容易被误判成网络问题,于是反复重启客户端或切换节点,真正的原因反而被放过。
归一化的第一步是承认错误信息有三个来源层,而不是一个字段。传输层的 HTTP 状态码决定请求是否成功落地,各厂商通用;协议层的 error.type 与 error.code 决定厂商自己如何归类;语义层的 error.message 与 request id 决定具体是哪次调用、哪个参数出的问题。映射表因此必须以状态码为骨架、以 type 和 code 为修正项,否则跨厂商比对时会失去共同基准。
一张能用的映射表至少要覆盖六类,并且每类都要写清在客户端里对应的可操作动作。401 与 403 归为鉴权与权限,检查 key 是否过期、是否带多余空格、是否把某家厂商的 key 填到了另一个服务商条目下;404 归为模型或路径不存在,先核对模型名拼写,再看 base_url 是否缺少或重复了 /v1;429 归为限流与配额;400 归为参数与上下文;5xx 归为上游故障;没有状态码的归为本地网络、代理、证书与超时。归类之后动作才有指向,而不是笼统地「换个 key 试试」。
在 Cherry Studio 里定位错误码,优先看请求日志,而不是对话气泡上的提示。气泡上的 message 通常被截断,模型服务设置页里的连通性测试能快速区分是配置问题还是上游问题,而完整的状态码、响应头与请求体需要从日志文件或开发者工具的 Network 面板里取。不同版本的入口位置会有差异,找不到时以官方说明为准,但排查顺序不变:先看状态码,再看 error.code,最后才读 message。
复现步骤要固定到最小变量,否则抓到的错误码彼此不可比。固定同一个厂商条目、同一个模型名、同一段最短输入,先跑一次连通性测试,再发一条只有几个字的对话;两次结果不一致时,差异通常来自模型名后缀(例如带日期版本)或该条目上单独配置的代理地址。把 base_url、模型名、状态码、error.code、request id 抄在同一行,才谈得上归一化查看。
429 是最容易被误读的一类,因为它既可能来自上游,也可能来自链路中间。上游返回 429 通常带 retry-after 或 x-ratelimit-remaining 之类的响应头,指向速率或配额限制;如果一个限流响应头都没有,只有一句通用文案,问题更可能出在本地并发过高,或多标签页、多助手同时发起请求。正确做法是保留响应头,按小时统计 429 占比,而不是看到一次就改配置。
400 里要单独拆出上下文超限,否则会把输入太长误记成参数写错。部分厂商对超出上下文长度返回 400 并附 context_length_exceeded 这类 code,另一些用 413 或 422 表达同一件事,归一化时应统一归到「输入超出模型窗口」,对应动作是压缩系统提示、裁剪历史消息或换更长上下文的模型,而不是去调整 temperature、top_p 这些采样参数。
流式响应会掩盖错误码,这是归一化查看里最容易被忽略的盲区。SSE 场景下 HTTP 状态早已返回 200,真正的错误写在流内的 error 事件或最后一帧里,界面表现只是回复中断。把流内 error 事件纳入映射表、与 4xx 和 5xx 同级记录,才能避免统计里出现一批「状态成功但内容为空」的调用,否则错误率会被系统性低估。
连接类失败没有错误码可查,需要用分层排查替代查表。先确认 base_url 的协议、域名、端口与路径后缀,再逐项区分 DNS 解析失败、TLS 证书不匹配、代理拦截和读超时;同一台机器上浏览器能打开目标地址而客户端打不开,多半是客户端没走系统代理,或者代理只对部分进程生效。这类问题归到「网络与代理」一类,不要和上游 5xx 混在一起统计。
归一化的产出应该是一张可统计的表,而不是一次性的判断。建议字段包括时间、厂商条目、模型名、归一化分类、原始状态码、原始 error.code、request id 与耗时;按天看分类分布,能直接把「key 到期」这种单点故障和「上游 5xx」这种批量故障区分开。本地日志文件适合长期留档,开发者工具适合单次复现,两者配合比截图记录可靠得多。
归一化只解决看得懂,不解决责任归属。同样的 5xx 在自建代理或中转链路上可能被改写,遇到无法归类的错误体时,保留原始响应全文与 request id 比继续猜分类更有价值;若链路中间还有服务商,应把原始错误体一并提供,方便对方回查。归一化查看的边界就在这里:它提高判断效率、统一统计口径,但不替代厂商侧的日志与可用性承诺。