21. 问题诊断与处理

完整版章节。内容按 2026.10 主线代码与运行环境界面核对；具体入口以当前许可、账号权限和交付环境为准。

返回概览 · 完整版目录 · 下载完整 PDF

本章内容：本章面向值班管理员与替调用方排查问题的技术支持人员，按「现象」组织：调用失败、请求不返回、被限流、被熔断、被护栏拦截、上游报错时分别从哪里看、由谁处理；然后说明请求详情怎么读、常见错误码怎么对应；最后说明如何把零散的单次失败归纳成系统性问题。

21.1 排查的第一步：拿到三个信息

适用场景：调用方报告「调不通」，但说不清原因。

动手看页面之前，先索取三样东西，后面每一步都依赖它们：

1. HTTP 状态码：401、403、404、429、502、503、504 分别落在不同环节。
2. 响应体中的 reason：平台给出的稳定原因码，比状态码更精确。同为 429，TRAFFIC_RATE_LIMITED 是本地限额，LLM_RATE_LIMITED 是上游限流，处理人不同。
3. 响应头中的 x-request-id：用它可以直接定位这一次调用。

操作步骤

1. 进入「管理后台 › 运行总览 › 请求」，在搜索框粘贴 x-request-id。
2. 调用方没保留标识时，改按「发起人」「接入凭据」与时间范围筛选，并把「结果」设为「失败」。
3. 打开记录，进入请求详情。

你会看到

• 「时延与成败」：状态、HTTP 状态码、失败发生在哪个环节、错误类别。
• 「路由与改写 › 命中记录」：命中了哪条规则、做了什么处置。
• 「路由与改写 › 上游尝试」：有尝试记录说明请求已发到上游；没有说明它在网关内部就被拦下了。这一条立刻把「调不通」分成两半——要么改规则，要么查上游。

21.2 调用失败：认证、授权与模型不存在

适用场景：调用方收到 401、403、404，请求根本没发到上游。

操作步骤

1. 在「管理后台 › 组织与权限 › 模型分组」打开目标分组的「可用范围」，核对调用方或其部门、职能组是否在内。
2. 在「API 密钥管理」中按名称或前缀搜索该密钥，核对是否「已禁用」。
3. 若为 403，在请求详情「命中记录」中确认是否由流量规则拒绝。

你会看到

• 三种协议各自返回原生错误结构，但携带同一个 reason。同样的认证失败，OpenAI 返回 invalid_api_key，Anthropic 返回 authentication_error，Gemini 返回 UNAUTHENTICATED。
• 400、401、404、413 这类请求侧错误的响应头带 x-should-retry: false，表示原样重试不会改变结果。

注意：403 有两个来源——可用范围未授权，或被流量规则拒绝。前者改「可用范围」，后者改规则。处理前先在「命中记录」确认是哪一种，否则会在错误的地方改配置。

21.3 请求一直不返回：超时

适用场景：调用方等待很久后收到 504，或客户端先于平台超时断开。

超时由两层构成：网关等待上游的时间（在规则里配置），以及调用方客户端自己的超时。先分清是哪一层先到。

操作步骤

1. 在「流量规则 › 新建规则」中限定条件，例如「调用类型 = 模型调用」加一个专属请求头，避免影响其他调用方。
2. 添加处置动作「应用限额」，展开「并发、熔断与超时（可选）」。
3. 打开「上游调用超时」，填写「连接超时」与「请求超时」（毫秒）。
4. 保存，在「确认变更」中核对后点「确认并应用」。

你会看到

• 上游未按时响应时，客户端收到 504：

  {"error":{"message":"The upstream model service timed out.","type":"server_error","code":"timeout","reason":"LLM_TIMEOUT"}}

• 这类请求有上游尝试记录，上游耗时接近或超过配置的请求超时值。

注意

• 请求超时按上游真实响应时间设置。过小会把正常的长回答判成超时；过大则客户端已断开而网关还在等，白白占用连接。
• 毫秒级超时值只适合在测试环境验证超时链路，不要用于生产规则。
• 上游确实慢时，应同时考虑增加供应商账号、配置备用档位（见 21.7）或换更快的模型。

21.4 被限流：请求速率、并发与排队

适用场景：调用方收到 429，或需要为某个调用方设定调用上限。

操作步骤

1. 在「流量规则 › 全局限额」点「新增限额」，填写名称。
2. 选择「计数维度」（如「按 API 密钥」），填写「匹配条件」选定调用方。
3. 选择「时间窗」（如「分钟」），填写「周期内请求数」与「即时突发量」。
4. 在「超限处理」中选择动作，按需填写附加参数，保存。

你会看到：三种超限动作表现各不相同。

• 选「返回固定应答」时，响应体带 zenova_degraded: true、reason_code（如 quota_exceeded）与 retry_after_seconds，usage 各项为 0，该次调用不计费。

注意

• 「返回固定应答」返回 200 而非错误码。调用方只看状态码会把降级应答当成正常回答，应以 zenova_degraded 或 reason_code 判断。
• 限额在调用结束后记账，单次调用可能把用量推过限额，从下一次调用起才被拒绝；不要在临界点上依赖「一次都不超」。

21.5 熔断：目标连续失败时快速拒绝

适用场景：上游持续超时或连续报错，希望后续请求立即失败，而不是每个请求都等满超时。

操作步骤

1. 在流量规则中添加处置动作「应用限额」，展开「并发、熔断与超时（可选）」。
2. 打开「熔断」，填写「统计窗口」（如 30 秒）、「最小调用样本数」、「失败率阈值」、「慢调用阈值」与「慢调用率阈值」、「熔断持续时间」、「半开探测次数」。
3. 保存并在「确认变更」中应用。

你会看到

• 熔断打开后，客户端收到 503：

  {"error":{"code":"circuit_open","reason":"TRAFFIC_CIRCUIT_OPEN","retry_delay_seconds":29}}

• 熔断期间的请求上游耗时为 0 毫秒，说明确实被快速拒绝、没有再去打扰上游。
• 熔断持续时间到期后，平台按「半开探测次数」放少量请求试探，探测成功即恢复。

注意

• 熔断是规则级配置，只作用于命中该规则的请求；停用规则即恢复原状。
• 修改并重新下发规则会重置该规则的熔断状态。核对是否真的自动恢复时，应在不改配置的前提下等待熔断持续时间到期再观察。
• 熔断解决的是「不要继续等」，不是「上游已经好了」。频繁触发时根因仍在供应商侧。

21.6 被护栏拦截

适用场景：调用返回 403，但既不是可用范围问题，也不是限流。

操作步骤

1. 打开请求详情，看「命中记录」中命中的规则、类别与处置。
2. 把请求内容与规则条件对照，判断是否误拦。
3. 确认误拦时调整规则的条件或处置（例如把「拦截」改为「仅记录」观察一段时间）；确认违规时通知调用方修改请求内容。

你会看到：护栏拦截表现为 403，与「可用范围未授权」状态码相同，区别在于命中记录里能看到具体的护栏类别与处置。

注意

• 护栏的检测与处置都写在流量规则里，没有独立的护栏配置页。
• 出向护栏拦截的是模型返回的正文，因此同一请求可能已经产生上游费用，而调用方拿到 403。核对费用以请求详情中的用量为准。

21.7 上游报错与故障转移

适用场景：请求已到达上游，但上游返回错误、连不上或超时。

前提：模型至少有两个可用上游，或规则中配置了两个以上可用目标。

操作步骤

1. 打开流量规则详情，在「规则编排」中把转发动作设为「转发到」，启用「故障转移（高可用）」。
2. 按优先级排列目标：第 1 档主用，第 2 档起备用。
3. 勾选触发条件：上游连接失败或中断、上游超时，以及上游返回的状态码（400、429、500、502、503、504）。
4. 填写最多尝试次数与时间上限（如最多 3 次、120 秒），保存并应用。

你会看到

• 主用失败、备用成功时，客户端拿到 200，响应头带 x-zenova-route-rule，响应体 model 字段为实际提供服务的备用模型。
• 失败状态码不在触发集合内时，客户端原样收到该状态码，错误体带 details.upstream_status 与 upstream_message；这说明平台既没有重试，也没有切换目标。
• 「规则编排」把故障转移表达为一条链路（第 1 档 → 第 2 档），并说明「备用目标用尽或达到尝试上限后，停止转移；已收到响应则按响应处理，无可用响应时返回错误」。
• 「实时流量」显示每条规则的调用次数、成功率，以及「故障转移 N 次（兜住 N 次）」；各目标分行给出转出、转入次数与费用。同一次调用在两档各留一条尝试记录，互为一出一入。

注意

• 400 这类参数错误的请求，重试到备用目标同样会失败。是否把它放进触发集合，取决于备用目标的参数约束；不确定时不要勾选 400。
• 上游错误原文可能通过 details.upstream_message 透传给调用方，其中含上游侧的请求标识。对外分享请求记录时应留意。

21.8 常见错误码与处理

同一状态码下，reason 决定责任人。

通用规则

• 所有响应都带 x-request-id；OpenAI 与 Gemini 的错误体中另有 request_id，Anthropic 的在 details 中。
• x-should-retry: false 表示重试无意义；429 带 Retry-After，按其中秒数退避。
• 错误体不含上游地址、上游密钥或堆栈，可直接转给调用方或外部协作方。

注意：400、413 这类由请求内容引起的错误，改网关配置无济于事，必须先修调用方的请求。

21.9 用使用洞察发现系统性问题

适用场景：单次失败已处理完，但同类问题反复出现，或需要回答「这半个月的调用哪里不顺」。

前提：账号为租户管理员；已有经过网关的会话数据。

操作步骤

1. 进入「管理后台 › 使用洞察」，默认打开「总览」，选择统计周期（如近 15 天）。
2. 查看五组指标：采用（覆盖率）、效果（任务达成率、一次达成率）、效率（每次达成的费用、无效消耗占比）、用法（需求清晰度）、平台因素（外部服务与工具失败的贡献），以及「需要关注」清单与按天趋势。
3. 切到「问题」页签，按严重度、影响或费用浏览。
4. 打开一个问题，阅读「概况」中的分布特征、原因分析与修复建议，再用「证据」页签查看命中的会话。
5. 处理后点「标记为」记录处置状态。

你会看到

• 页面右上角提示「正在按最新规则重新分析历史会话，完成前部分指标可能变动」。
• 问题列表的列：严重度、问题、负责方、影响会话数、次数、费用、近 15 天走势、状态。常见问题包括上游服务报错（含被限流）、请求被本企业额度拒绝（预算不足）、会话内上下文反复压缩、提示词缓存反复失效等。
• 问题详情给出费用、影响会话、次数、最近出现时间与每日发生次数图，以及按客户端、报错类别等维度的分布特征。
• 原因分析与修复建议末尾注明「此段分析生成于某日某时，此后数据已更新，次数与会话数以上方关键数字为准」。
• 「证据」页签列出命中的会话：在做什么、员工、部门、命中次数、时间。

注意

• 首次打开需要较长时间完成分析，页面会逐步填充数据，不必反复刷新。
• 诊断以「问题」为单位跨会话聚合，单次失败的调用不会单独成为问题；排查单次调用请用 21.1 至 21.8 的方法。
• 原因分析是一段时间点上的结论，其后的数据变化不会回写；引用时以关键数字为准并注明时间。
• 「标记为」会改变他人可见的处置状态，多人共用一个租户时先与同事确认。

能力说明

---

上一章：20. 网关请求、会话与根因定位 · 下一章：22. 告警、通知、留存、导出与操作审计