401 / 403：鉴权与权限
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 |
api key verification unavailable |
平台的密钥校验服务暂时不可用，与 Key 是否正确无关 | 稍后重试；持续出现时查看服务状态 |
图 1：鉴权失败时在日志详情核对状态、请求标识与错误来源；图示为无效密钥演示。 截图为演示数据，点击图片可查看原图。
- 请使用 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，见模型不可用 |
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：限流与配额 |
安全围栏拦截
Request blocked by guardrail policy 的原文不包含策略名称或命中内容，请按 error.code 判断命中的策略类型：
error.code |
策略类型 |
|---|---|
guardrail_client |
客户端访问控制：按来源 IP、工具名或 User-Agent 限制调用 |
guardrail_context |
意图安全检测：请求意图被判定有风险 |
guardrail_sensitive |
敏感信息检测：请求包含个人信息、凭证或敏感关键词 |
guardrail_injection |
提示词注入检测：请求疑似提示词注入 |
guardrail_model |
模型访问控制：所选模型不在允许范围内 |
同样的请求重试会得到同样的结果。调用方可以调整请求内容或换用允许的模型；需要查看命中详情或调整策略时，请账号管理员查看安全围栏与语义审计。模型策略按实际选中的模型检查，对虚拟模型同样生效。
判断错误来自网关还是上游
请求日志列表的「状态说明」列会标明来源是「网关」还是「上游」，以及具体原因。上游返回 401 或 403，通常是上游凭证被拒绝：使用 BYOK 时，请账号管理员在服务商处确认凭证有效、额度充足，并在 BYOK 中重新测试连接。上游只返回状态码、没有响应体时，网关会补上 error.code（如 upstream_unauthorized、upstream_forbidden），并带 "generated_by": "ai-gateway" 标明这段内容由网关生成。
常见问题
模型在控制台能看到，为什么 API Key 调用返回 403？
答： Key 只能调用它所属工作空间中已开通的模型。在模型目录中看得到，不代表该工作空间已开通，也不代表部门、成员或 Key 的模型策略允许调用。先在该工作空间的模型广场确认模型已开通，再请账号管理员检查安全围栏中的模型策略，详见模型授权。修改客户端里的模型展示名不能绕过权限。
提交鉴权问题时，需要提供哪些信息？
答： 响应中不包含请求 ID。请记录调用时间、端点、模型、API Key 的名称和报错原文；如果能在日志中找到这次请求，再附上日志详情顶部的 Request ID。401 请求无法归属到任何 Key，不会出现在日志中。不要提供 API Key 明文、完整的 Authorization 头或敏感的输入输出。