调用 AI 接口返回“密钥无效”（常见是 401 或 403，错误体里出现 invalid api key、authentication failed 之类的提示），不要立刻去后台重新生成一个密钥。多数情况下问题出在请求头拼装、密钥读取链路或者请求经过的中间层，密钥本身并没有输错。先判断是“密钥内容不对”“密钥传递方式不对”“密钥在这套环境下没有这项权限”中的哪一种，再动手改，能少走很多弯路。
AI 接口提示密钥无效时，先看原始 HTTP 状态码和错误体结构，再依次核对请求头格式、密钥读取来源、端点与项目归属、密钥状态与权限范围。若本地用 curl 能通而服务内不通，问题通常在环境变量或中间层；若两处都不通，再考虑密钥被禁用、过期或额度耗尽。验证以一次最小请求返回成功状态和正常响应体为准，轮换密钥前建议保留旧密钥可回退。
先确认当前场景和目标
这个判断成立的前提是：请求确实发到了 AI 服务提供方的鉴权入口，并且你已经拿到明确的失败响应。若客户端只弹出“请求失败”而没有状态码，先抓原始响应，否则后面所有排查都是猜的。
动手前需要先确认这几项信息：
- HTTP 状态码是 401 还是 403。401 通常指凭据缺失或无法识别，403 更偏向凭据已识别但无权访问该资源，两者排查方向不同。
- 错误体是标准结构（例如带 error.type、error.message 字段）还是网关或中转层自定义的文本。后者未必反映真实原因。
- 密钥从哪里来：环境变量、配置文件、密钥管理服务，还是写死在代码里。这决定了要查哪一段链路。
- 请求是否经过自建网关、反向代理、Serverless 平台或第三方中转，这些环节可能改写或丢弃请求头。
- 同一个密钥在哪些环境使用，是否跨项目、跨区域共用一个密钥。
按这个顺序处理
建议按从外到内的顺序排查，每一步只改一个变量，避免改完后无法确定哪一步生效。
- 看原始响应。用 curl 带 -i 参数发一次最小请求，确认状态码和完整响应体。下面是一个通用骨架，BASE_URL 需要替换成该服务完整的对话端点，模型名换成你有权限使用的轻量模型：
curl -i -X POST "$BASE_URL" \
-H "Authorization: Bearer $AI_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"<your-model>","messages":[{"role":"user","content":"ping"}],"max_tokens":8}'- 核对请求头格式。常见错误包括：缺少 Bearer 前缀、Bearer 与密钥之间多一个空格、密钥被复制时带入换行或制表符、从文件读取时末尾多了一个 \n。这类问题在日志里肉眼很难发现。
- 检查密钥读取链路。在代码里打印密钥长度和首尾各四位（不要打印完整密钥），确认不是空串、没有被截断、没有多余空白。Python 可以这样自查：
import os
k = os.environ.get("AI_API_KEY", "")
print(len(k), repr(k[:4]), repr(k[-4:]))
print("has_whitespace:", k != k.strip())如果 has_whitespace 为 True，说明环境变量里带了空白字符，需要回到注入该变量的地方去清理，而不是在代码里 strip 掉后继续用。
- 核对端点和归属。部分平台的密钥与项目、组织或区域绑定，把密钥用在不同 base_url 上会出现鉴权通过但资源不可用，或者直接判为无效。确认请求地址与该密钥所属环境一致。
- 排查中间层。如果本地 curl 能通、服务内不通，重点看网关是否透传 Authorization 头、是否做了请求头重写、Serverless 平台的环境变量是否注入到了运行时。
- 最后才查密钥状态。到控制台确认密钥是否被禁用、是否已过期、额度是否耗尽、是否配置了来源 IP 限制、权限范围是否包含所调用的模型。
改完后怎么验证
验证不要用业务流程做，用一个最小请求即可：短提示词、小 max_tokens、单轮对话，减少干扰因素。
- 预期信号一：HTTP 状态码从 401/403 变为成功状态。
- 预期信号二：响应体是正常结构，含 choices 或等价的输出字段，而不是错误对象。
- 预期信号三：在你的实际运行环境（容器、CI、线上服务）里重复同一次请求，同样返回成功。只在本地通不算完成验证。
- 对比验证：保留一份失败时的原始响应，和成功响应并排比较，确认差异确实来自鉴权环节。
- 日志检查：确认日志中打印的请求头已脱敏，不会因为排查而把密钥写进日志系统。
如果换密钥后才通，建议再用旧密钥发一次请求，确认旧密钥是“已失效”还是“本来就没问题”，避免把环境问题误判成密钥问题。
容易忽略的边界
以下几类情况容易让排查停在错误的方向上：
- 密钥轮换存在过渡期。新建密钥后旧密钥可能仍有一段时间有效，也可能立即失效，取决于平台策略。轮换期间建议新旧并存，确认新密钥在全部环境可用后再停用旧的。
- 权限不足会被报成密钥无效。部分服务的 403 与 401 提示文案接近，实际是密钥有效但无权调用某个模型或某个项目下的资源。这种情况换密钥不能解决，要调整权限范围。
- 中转层会伪造或改写错误。经过第三方网关时，返回的“密钥无效”可能是上游透传，也可能由网关自身产生。需要看响应头里的服务标识，或临时直连服务方地址做对照。
- 配置文件的解析差异。.env 文件中给值加引号，部分解析器会连引号一起读入，导致密钥末尾多出字符；shell 中导出含特殊字符的密钥则需要加引号。两种场景的处理方式不一致。
- 不适合继续排查的情况。如果确认密钥已在控制台被删除或明确过期，不要再在代码层做兼容，直接按平台的密钥管理流程重新签发并更新配置。回退建议是保留上一版配置的备份和变更记录，出问题时能快速切回。
- 不要把密钥放进前端或客户端。为了绕过鉴权失败而在浏览器或移动端硬编码密钥，会让密钥暴露在分发产物里，这个问题比鉴权失败本身更难收拾。