一次中转请求返回 401 后的排查笔记

请求经过中转后返回 401，最容易出现的误判，是把它直接读成“模型服务商的密钥无效”。这个状态码通常表示请求未通过身份验证，但单凭它，无法确定拒绝发生在哪一层。更可靠的办法，是把几组可能性并排检查：入口与上游、密钥与协议、原始响应与客户端提示。

§ 中转入口拒绝，与上游鉴权失败

入口这一侧：客户端提交的凭据可能缺失、失效，或不属于当前请求指向的服务。请求可能尚未被转发，就已经收到 401。此时应核对目标地址、凭据来源，以及客户端实际发送的鉴权字段。

上游这一侧：中转已经接收请求，但调用后续服务时遇到鉴权失败。中转可能保留上游状态，也可能转换错误格式。此时，本地反复更换同一把密钥通常不能解决问题，应结合响应中的来源说明和平台侧记录定位。

两者对客户端都可能表现为 401。响应正文中的错误类型、脱敏后的错误消息，以及可用的请求标识，比状态码本身更有区分力。不过，这些字段只是线索；没有明确来源信息时，不宜断言是哪一侧拒绝。

内容检查：确认使用的是目标平台签发的密钥，而不是另一家服务的凭据。检查复制时是否夹带空格、换行或引号，以及旧密钥是否已经撤销。不要把完整密钥粘贴到工单、聊天或公开日志中。

发送检查：配置文件里有值，不代表运行中的进程读到了它。终端、编辑器插件、容器和持续集成任务可能使用不同环境。优先确认当前进程读取的配置位置，以及出站请求是否包含协议要求的鉴权字段；记录“存在或缺失”即可，不必输出字段原值。

这组比较可以避免一种常见绕路：明明是环境变量没有传入，却连续创建多把新密钥。先证明凭据抵达请求，再判断凭据是否有效。

地址这一侧：核对客户端最终拼接出的主机和路径。有些工具需要填写基础地址，有些需要填写完整接口地址。路径重复或请求落到另一条网关路由，可能使返回结果偏离预期；不能因为收到了 HTTP 响应，就认定配置正确。

协议这一侧：Vana API 的统一入口为 https://api.vanaapi.com，支持 OpenAI 兼容接口，也支持 Anthropic Messages 和 Gemini 原生协议。统一入口不意味着不同协议的路径、请求字段和鉴权方式可以任意混用。应按当前客户端所采用的协议核对配置。

例如，用 OpenAI SDK 请求 Gemini 2.5 Flash 时，应检查兼容接口的配置，而不是仅凭模型名称改用原生协议字段。模型选择和请求协议是两个独立维度，单独一个 401 无法证明模型名称有误。

摘要这一侧：命令行工具或 SDK 可能只显示“认证失败”，隐藏响应正文，也可能把不同来源的异常归为同一类。摘要适合提醒失败，不一定足以解释原因。

原始响应这一侧：在安全范围内保留状态码、响应内容类型、错误正文和请求标识。若正文是代理生成的网页，而不是预期的接口错误结构，可以优先检查网络代理或网关；但仅凭外观仍不能最终确认来源。

对外提供日志前，还要移除鉴权头、Cookie、查询参数中的密钥，以及请求正文中的私人内容。排错需要的是请求路径和错误证据，不是完整业务数据。

原样重试：401 通常不适合像临时网络错误那样持续重试。凭据或配置不变，重复发送往往只会增加噪声。也不要把它直接当作余额不足、限流或权限不足；这些情况应结合具体错误说明区分。

最小复现：固定同一协议、同一模型和最短输入，先验证一条基础请求，再逐项恢复工具配置。每次只改一个变量，并记录时间、客户端版本、路径和请求标识。若最小请求成功而原工具失败，优先比较两者的出站配置；若都失败，再继续核对凭据或联系平台支持。

如果准备使用 Vana API，可以创建账户并按对应协议配置密钥，再做一次最小验证。读懂 401 的重点，不是立即找到一个看似合理的解释，而是用可重复的证据，逐步缩小拒绝发生的位置。