Cherry Studio 调用多个模型 API 时错误码格式不一致,怎样归一化查看并定位原因?

在 Cherry Studio 中,归一化查看多模型 API 错误码的关键不是逐条读界面英文报错,而是在请求出口或本地日志层统一映射 HTTP 状态码、供应商错误字段和 request_id,再按类别、可重试性、建议动作回看。完全直连且未开启日志时只能看到界面提示,无法事后归一化。

在 Cherry Studio 中归一化查看多模型 API 错误码,可靠做法是在请求出口或本地日志层建立统一映射,把 HTTP 状态码、供应商 error.code/type/message、request_id 归一为 category、normalized_code、retryable 等字段,再回到对话错误提示中对照。这个方法适用于请求经过自建代理、网关或可导出日志的客户端;完全直连且未开启日志时,只能看到界面提示,无法事后归一化,需要改用可观测的请求出口或抓包工具补齐证据。 不同供应商的错误体结构不同,只看 message 会把同一类故障拆成多种说法。OpenAI 风格通常在 error 对象里放 message、type、code,Anthropic 风格常用顶层 type 加 error 对象,其他厂商还可能把错误放在 data 或流式事件里;同一个 401 在不同平台上的文案也不一样。归一化应以 HTTP 状态码加供应商 code 为主键,message 只作补充,不适用于只返回自然语言、没有结构化字段的私有接口。这样同一张表既能给技术排障看,也能在 Cherry Studio 的对话错误提示里显示为可读类别。 统一字段至少要包含 normalized_code、category、http_status、provider、provider_code、retryable、request_id、raw_message、model、base_url 和 timestamp。category 建议固定为鉴权、限流与额度、参数与上下文、模型不可用、服务端错误、网络与超时、内容审核七类,retryable 则按状态码和供应商语义单独判定。字段固定后,排查时不必反复猜英文含义,直接按类别过滤;展示时保留原始 message 与 request_id 供复核,避免归一化字段掩盖供应商返回的事实。 采集点应覆盖客户端发请求前的参数校验、HTTP 响应的状态码与 body、流式 SSE 中的 error 事件三层。流式请求常见 HTTP 200 但流内返回错误,必须解析 event 或 data 里的 error 字段,否则会误判为成功;只在界面看请求失败会丢掉 code 和 request_id。自建代理还应记录上游耗时和重试次数,便于区分客户端超时与上游超时,也能判断错误是首次出现还是重试后仍失败。 在 Cherry Studio 侧排查时,先确认 provider、base_url、model 三元组。同一模型经不同中转或代理时错误码可能完全不同;三元组不清,后续映射表再完整也无法定位。查看对话错误提示中的原始信息,若版本支持日志或开发者工具,导出对应网络响应;不支持时可用系统代理或抓包工具观察 4xx/5xx 的响应体,但要对 Authorization 和 cookie 脱敏。企业终端禁止抓包时,应改用可观测的请求出口,而不是在客户端反复重试。 映射表可按常见状态码起步,但不能把 400 一律归为参数错误。401 归为 AUTH_INVALID,403 归为 AUTH_FORBIDDEN 或额度不足,404 归为 MODEL_NOT_FOUND,429 归为 RATE_LIMITED,5xx 归为 UPSTREAM_ERROR,连接超时归为 NETWORK_TIMEOUT,内容审核拦截归为 CONTENT_BLOCKED;message 含上下文长度、图片尺寸、工具调用格式时,应拆成 CONTEXT_OVERFLOW、INVALID_IMAGE、TOOL_SCHEMA_ERROR 等子类。映射表要版本化,供应商调整错误结构时同步更新,否则新旧错误会混在同一类里。 归一化后的展示应给类别、是否可重试、建议动作和 request_id,而不是只显示一段英文 message。429 读取 retry-after 后再退避,5xx 用指数退避,401 和 403 不应自动重试;流式响应已经输出部分内容时,重试还要避免重复计费和重复消息。自建归一化层会增加日志存储与代理转发成本,但能显著缩短定位时间,成本主要落在日志保留周期和字段脱敏上,而不是映射表本身。 多模型并发场景要按 provider、model、base_url 三个维度聚合错误率,并带会话 ID 或请求 ID。否则同一个 key 在 A 模型上报 429、在 B 模型上报 404 时,无法判断是密钥额度、模型权限还是代理路由问题。建议看 5 分钟窗口内的错误分布,再把客户端本地错误(配置缺失、URL 拼错、超时设置过短)与上游错误分开统计;聚合结果用于定位共性,不用于替代单条 request_id 的明细核查。 最小复现流程是用同一 key、同一 model、同一 base_url,通过 curl 或 SDK 发一条短消息,对比 Cherry Studio 的结果。curl 正常而客户端报错,查客户端参数、代理、超时和流式开关;两边都报错,查密钥、额度、模型权限和上游状态。保留 request_id 供供应商查日志,比反复截图错误弹窗更有效;复现时记录时间戳、模型名和出口地址,能快速判断问题落在客户端配置、代理路由还是上游服务。 归一化只改变错误的可读性和分类,不改变供应商返回的事实。不能把 429 伪装成成功,也不能把 5xx 重试到用户无感知;日志中的 Authorization、cookie、prompt 和 completion 应脱敏或加密,错误样本按 7 到 30 天保留即可。对外展示给非技术用户时只给类别和建议动作,原始 code 与 request_id 放在详情里供技术复核,这样既保留排障证据,也避免把敏感内容扩散到普通界面。 落地顺序可以按先采集、再映射、后展示推进。先在请求出口把状态码、错误体、request_id 和三元组记全,再建立带版本号的映射表,最后把类别、可重试性、建议动作做进 Cherry Studio 可回看的错误提示。若暂时没有日志层,至少保留对话错误原文与截图中的 request_id,并记录当时使用的 provider、base_url、model;这比只记请求失败四个字更有排障价值。 归一化层要保留原始响应样本,但必须控制访问权限和保留周期。映射表解决的是可读性和分类,原始样本解决的是取证;两者混在一起会带来泄露风险。建议把 raw_message、provider_code 和 request_id 放在技术详情,把 category、retryable 和建议动作放在普通视图,并给映射规则变更留记录。这样既能用统一口径查看错误,也能在供应商调整字段后快速回溯,不会因为一次映射改动丢失定位线索。