401 · 排错
API 返回 401 怎么排查：Key、鉴权头与请求地址
更新日期：
401 说明当次请求未通过认证，不一定表示 Key 本身已失效。错误平台的凭据、重复路径、错误鉴权头、环境变量未生效，都可能让原本可用的 Key 在某条请求中失败。先固定一个最小请求，逐项检查。
1. 先记录失败的请求
记录最终域名与路径、HTTP 状态、协议、模型 ID、发生时间、错误字段，以及响应中可用的请求 ID。只分享脱敏内容，不发布完整 Authorization 或 API Key。
官网 tikway.ai 与 API api.tikway.ai 作用不同。模型请求应按对应协议发送到 API 域名，而不是向官网首页 POST。
2. 对照协议检查鉴权
| 协议 | 文本请求路径 | 示例鉴权 |
|---|---|---|
| OpenAI Chat Completions | /v1/chat/completions |
Authorization: Bearer YOUR_KEY |
| Anthropic Messages | /v1/messages |
x-api-key: YOUR_KEY，另带 anthropic-version: 2023-06-01 |
| Gemini generateContent | /v1beta/models/{模型ID}:generateContent |
x-goog-api-key: YOUR_KEY |
以Tikway 鉴权文档和当前错误信息为准。上表给出常用组合，不代表每种凭据或所有路由都接受互换鉴权方式。
3. 检查实际生效的 Key
确认使用 Tikway 账户创建的 Key，复制时没有空格或换行，且没有误读另一终端、容器或 IDE 中的旧环境变量。检查 Key 是否被删除、禁用或受到权限限制。可以检查变量是否为空，避免直接打印变量内容。
SDK 的显式配置、环境变量、配置文件和客户端服务商选项可能同时存在。只修改一个未被当前进程读取的文件，不会改变真实请求。
4. 检查基础地址如何拼接
例如 OpenAI SDK 使用 https://api.tikway.ai/v1 后会追加 /chat/completions；Claude Code 的配置方式不同，参考独立指南。
重点检查是否出现 /v1/v1/、把完整操作路径当作 Base URL、使用官网域名、或在代理层重写了路径。一次测试只修正一个可疑项，再比较结果。
5. 区分认证、余额与限流
| 返回结果 | 下一步 |
|---|---|
| 401，提示无效或缺少凭据 | 核对 Key 来源、请求头和路由 |
| 403 | 结合消息检查权限与访问策略 |
429 + insufficient_balance |
检查余额；反复等待通常不能解决 |
429 + requests_per_minute_exceeded |
降低请求频率与并发 |
| 模型或参数错误 | 查目录中的 ID、协议和参数范围 |
不要对认证失败无限重试，也不要在没有核对错误内容时反复充值。详细说明见计费与报错教程。
6. 修正后怎样验收？
用Python 最小请求或Claude Messages 请求验证 HTTP 状态与有效正文，然后逐步恢复原客户端的流式、工具和历史消息。通过后保留脱敏的基线配置。