401 Unauthorized 或 invalid_api_key 的核心含义是：当前请求携带的认证信息没有被目标接口接受。它通常不是网络波动，也不应该靠重试解决。
直接答案
排查 401 的顺序是：确认 API Key 和 Base URL 属于同一平台，确认请求头只有一个 Authorization: Bearer，确认运行中的进程读取了当前 Key，最后检查最终请求路径是否只有一层 /v1。先用同一个 Key 请求 /v1/models；仍然返回 401 时停止重试并检查 Key 状态与账号权限。
30 秒判断问题在哪
先绕开 Cursor、Dify 等客户端，直接测试模型列表。以下命令只使用 AI快站 HK 创建的 Key；先在本地环境中设置 AIFAST_API_KEY，不要把其他平台的 Key 发到这个地址。
if [ -n "$AIFAST_API_KEY" ]; then
curl --connect-timeout 10 --max-time 30 -sS -i \
https://www.aifast.hk/v1/models \
-H "Authorization: Bearer $AIFAST_API_KEY"
else
printf '%s\n' 'AIFAST_API_KEY is not set'
fi根据结果分流：
| 结果 | 优先检查 |
|---|---|
| curl 也返回 401 | Key 内容、账号状态、请求头和目标平台 |
| curl 成功，客户端返回 401 | 客户端读取的环境变量、配置优先级和重复 Bearer |
| 一个域名成功，另一个域名 401 | Key 与 Base URL 不属于同一平台 |
| 偶尔成功、偶尔 401 | 多实例配置不一致、旧 Key 未替换或请求实际走了不同入口 |
模型列表返回 200 只证明这个请求被接受，不证明目标模型的生成接口、分组权限或余额全部正常。若模型列表受限或不支持，不能据此直接判断 Key 无效；按平台文档核对权限后，再用受控测试 Key 对目标接口发一条短请求，生成请求可能产生费用。
api_key_required 和 invalid_api_key 有什么区别？
前者通常表示服务没有收到它要求的认证信息，后者通常表示收到的凭证未被接受；不同网关的错误命名可能不同，应同时保留 HTTP 状态和脱敏错误正文。不要看到 api_key_required 就直接认定账号欠费。
| 请求类型 | 先核对什么 |
|---|---|
| OpenAI Compatible | 客户端通常代填 Authorization: Bearer；Key 输入框不要再加 Bearer |
| Anthropic Messages 或其他原生协议 | 按目标平台文档核对认证头和版本头，不把 OpenAI 的设置原样套用 |
| 模型列表成功，生成接口失败 | 比较两次请求的目标主机、认证来源、模型权限和错误正文 |
不要把完整 Key 粘贴到在线问答、Issue、日志或截图中。排错时只保留前后各 3 至 4 位用于区分不同 Key。
为什么 curl 能用，客户端仍提示 invalid_api_key？
这通常说明 Key 本身可用，但客户端没有发送同一份配置。优先检查客户端是否读取了旧环境变量、是否把 Bearer 重复添加、Base URL 是否被工作区配置覆盖，以及最终请求是否发往另一个域名。不要因为 curl 成功就不断创建新 Key；先在客户端诊断日志中核对脱敏后的 Key 指纹、目标域名和请求头来源。
同时检查最终路径是否出现 /v1/v1。确认结果后，回到客户端清理重复配置。
按顺序检查六个位置
1. Key 和 Base URL 是否属于同一平台
第三方平台创建的 Key 不能直接发给官方 OpenAI 地址，官方 OpenAI Key 也不应默认发给其他网关。先确认这两个配置来自同一个服务：
Base URL: https://www.aifast.hk/v1
API Key: 在 AI快站控制台创建的独立 Key如果正在从其他平台迁移，必须同时替换 Base URL 和 Key，不能只改其中一个。
2. Authorization 请求头是否正确
OpenAI Compatible 接口通常使用：
Authorization: Bearer sk-***常见错误包括：
- 写成
Authentication或其他请求头； - 遗漏
Bearer与 Key 之间的空格； - 客户端已经自动加
Bearer，配置值里又写了一次； - Key 前后带有引号、换行或复制时混入空格；
- 反向代理没有转发
Authorization请求头。
3. 当前进程是否真的读到了新环境变量
修改 shell 配置文件不等于已经更新正在运行的程序。先只确认变量是否存在和长度，不要输出完整内容：
test -n "$AIFAST_API_KEY" && echo "Key 已加载, 长度 ${#AIFAST_API_KEY}" || echo "Key 未加载"IDE、桌面客户端、Docker 容器和系统服务可能不会继承当前终端变量。修改后应重启对应进程，并在它自己的运行环境中检查。
4. 是否存在多套配置覆盖
检查项目 .env、用户级配置、工作区配置和启动参数。典型现象是：终端 curl 使用新 Key，但客户端仍从旧配置文件读取已撤销的 Key。
排查时一次只保留一个认证来源。确认成功后，再恢复需要的配置层级。
5. Key 是否仍然可用
确认 Key 没有被删除、禁用或轮换，账号状态也正常。不要用生产 Key 做公开排错；应创建权限和余额都受控的测试 Key。
6. 最终请求是否发到了预期域名
客户端界面里的 Base URL 不一定等于最终请求地址。通过客户端诊断日志或服务端请求记录确认：
- 最终主机名；
- 最终路径；
- 是否经过额外代理；
- 响应正文中的错误类型与请求 ID。
可以先用 Base URL 在线检查器 检查地址拼接，再回到客户端配置。
Python SDK 最小验证
import os
from openai import OpenAI
client = OpenAI(
base_url="https://www.aifast.hk/v1",
api_key=os.environ["AIFAST_API_KEY"],
max_retries=0,
timeout=30.0,
)
models = client.models.list()
print("模型列表请求成功, 返回模型数:", len(models.data))排查 401 时暂时关闭自动重试。认证配置不变，重发同一请求不会自行恢复。
不要用这三种错误方法
- 连续重试 401。 只会放大日志和请求量，不会修复认证。
- 把完整 Key 发给他人检查。 应撤销已公开的 Key，再创建新 Key。
- 同时改 Key、模型、代理和 SDK 版本。 变量太多，成功后也无法确认根因。
修复完成的验收标准
/v1/models使用目标 Key 稳定返回成功；- 最小非流式请求成功，并返回可解析正文；
- 客户端日志显示请求发往预期域名；
- 旧 Key 已撤销，仓库和日志中没有密钥明文；
- 401 不再进入自动重试队列。
认证通过后，可以继续使用模型质量检测检查模型声明、Token、SSE 和工具调用；如果出现 404 或模型不存在，转到model not found 与 /v1/v1 排查。