# 401 / 403：鉴权与权限

来源: https://platform.lyrouter.com/ai_gateway/docs/auth-errors
更新日期: 2026-10-14

401 表示网关没有认出请求中的 API Key；403 表示 Key 有效，但这次请求被拒绝。先读响应体中的 `error.message` 和 `error.code`，再按下表找到对应原因。通过 `/v1/messages` 调用时，错误会转换为 Anthropic 格式，不再带 `error.code`，请以 `message` 为准。

## 401：API Key 没有被认出

| 报错原文（`error.message`） | 原因 | 处理 |
| --- | --- | --- |
| `missing credentials` | 请求没有携带 API Key | 加上 `Authorization: Bearer <API Key>`；Anthropic 风格的客户端也可以使用 `x-api-key` |
| `invalid authorization scheme, expected 'Bearer'` | `Authorization` 头不是 `Bearer <API Key>` 格式。`Bearer` 区分大小写，`bearer sk-...`、直接写密钥、`Basic ...` 都会被拒绝；只写 `Bearer` 而没有密钥也会返回这个错误 | 按 `Bearer <API Key>` 格式填写 |
| `invalid api key` | 网关找不到这个 Key：复制不完整或带了空格、换行；Key 已删除、停用或过期；所属工作空间或创建人已停用；Key 刚创建，尚未同步到网关（通常几秒） | 重新复制完整的 Key；明文已丢失时删除旧 Key 并新建，见[创建工作空间与 API Key](https://platform.lyrouter.com/ai_gateway/docs/api-keys) |
| `api key verification unavailable` | 平台的密钥校验服务暂时不可用，与 Key 是否正确无关 | 稍后重试；持续出现时查看[服务状态](https://platform.lyrouter.com/ai_gateway/docs/status) |

（截图：鉴权失败时在日志详情核对状态、请求标识与错误来源；图示为无效密钥演示。）

- 请使用 LYRouter API Key，不要使用服务商的 API Key 或控制台的登录会话。
- 请求同时带 `Authorization` 和 `x-api-key` 时，网关只读取 `Authorization`。
- 通过环境变量配置 Key 的工具（如 Claude Code、Codex），修改后需要新开终端，或重新加载 Shell 配置。

## 403：请求被拒绝

| 报错原文（`error.message`） | `error.code` | 原因与处理 |
| --- | --- | --- |
| `api key expired` | — | Key 已超过有效期。新建一个 Key 替换它；过期一段时间后，同一个 Key 会改为返回 401 `invalid api key` |
| `your IP address is not allowed` | — | Key 开启了 IP 白名单，请求的来源 IP 不在名单中。网关按到达时的出口 IP 判断，在公司网络、代理或云服务器上调用时，出口 IP 可能与本机看到的不同 |
| `ip access control misconfigured` | — | Key 的 IP 白名单为空或包含无效的 IP / CIDR，网关拒绝所有请求。请 Key 创建者或账号管理员修正白名单 |
| `api key workspace is unavailable` | — | 网关暂时读不到 Key 所属工作空间的配置，属于平台侧临时问题，稍后重试 |
| `Model is not available in the model plaza` | `model_not_available` | Key 所属工作空间没有开通该模型，或在图像、视频、语音接口上使用了虚拟模型或 `lyrouter/auto`，见[模型不可用](https://platform.lyrouter.com/ai_gateway/docs/unavailable) |
| `Request blocked by guardrail policy` | `guardrail_*` | 请求命中安全围栏的阻断策略，见下文 |
| `Response blocked by guardrail policy` | `guardrail_sensitive` | 非流式请求的回答命中敏感信息策略。上游已生成回答，这次调用照常计费 |
| `Subject is blocked by an active security ban` | `guardrail_subject_banned` | Key 被安全围栏封禁，期间所有请求都会被拒绝。到达策略设置的自动解封时间后解除，或由账号管理员在安全事件中提前解除 |
| `该 API Key 已被永久封禁，无法恢复，请删除后创建新的 API Key。` | `api_key_permanently_banned` | Key 第 5 次触发错误率熔断后被永久封禁，不能解除。刚封禁时，后续请求由熔断检查返回 `该 API Key 因多次高错误率请求已被永久封禁，无法恢复，请删除后创建新的 API Key。`；封禁同步到网关后改为返回本行原文，两者含义相同。先修复持续报错的程序，再新建 Key，见[429：限流与配额](https://platform.lyrouter.com/ai_gateway/docs/rate-errors) |

### 安全围栏拦截

`Request blocked by guardrail policy` 的原文不包含策略名称或命中内容，请按 `error.code` 判断命中的策略类型：

| `error.code` | 策略类型 |
| --- | --- |
| `guardrail_client` | 客户端访问控制：按来源 IP、工具名或 User-Agent 限制调用 |
| `guardrail_context` | 意图安全检测：请求意图被判定有风险 |
| `guardrail_sensitive` | 敏感信息检测：请求包含个人信息、凭证或敏感关键词 |
| `guardrail_injection` | 提示词注入检测：请求疑似提示词注入 |
| `guardrail_model` | 模型访问控制：所选模型不在允许范围内 |

同样的请求重试会得到同样的结果。调用方可以调整请求内容或换用允许的模型；需要查看命中详情或调整策略时，请账号管理员查看[安全围栏与语义审计](https://platform.lyrouter.com/ai_gateway/docs/guardrails)。模型策略按实际选中的模型检查，对[虚拟模型](https://platform.lyrouter.com/ai_gateway/docs/presets)同样生效。

## 判断错误来自网关还是上游

[请求日志](https://platform.lyrouter.com/ai_gateway/docs/logs)列表的「状态说明」列会标明来源是「网关」还是「上游」，以及具体原因。上游返回 401 或 403，通常是上游凭证被拒绝：使用 BYOK 时，请账号管理员在服务商处确认凭证有效、额度充足，并在 [BYOK](https://platform.lyrouter.com/ai_gateway/docs/byok) 中重新测试连接。上游只返回状态码、没有响应体时，网关会补上 `error.code`（如 `upstream_unauthorized`、`upstream_forbidden`），并带 `"generated_by": "ai-gateway"` 标明这段内容由网关生成。

## 常见问题

### 模型在控制台能看到，为什么 API Key 调用返回 403？

**答：** Key 只能调用它所属工作空间中已开通的模型。在模型目录中看得到，不代表该工作空间已开通，也不代表部门、成员或 Key 的模型策略允许调用。先在该工作空间的模型广场确认模型已开通，再请账号管理员检查安全围栏中的模型策略，详见[模型授权](https://platform.lyrouter.com/ai_gateway/docs/authorization)。修改客户端里的模型展示名不能绕过权限。

### 提交鉴权问题时，需要提供哪些信息？

**答：** 响应中不包含请求 ID。请记录调用时间、端点、模型、API Key 的名称和报错原文；如果能在日志中找到这次请求，再附上日志详情顶部的 Request ID。401 请求无法归属到任何 Key，不会出现在日志中。不要提供 API Key 明文、完整的 `Authorization` 头或敏感的输入输出。