# API 密钥与调用所代表的人员

此类别中的每个代码：其含义、最常见的原因、应如何处理以及由谁处理。

[全部错误代码](https://www.azothos.ai/zh/docs/errors)

### `api_key_invalid`

- **含义**: 随调用发送的 Azoth API 密钥与任何有效密钥都不匹配。
- **最常见的原因**: 密钥已撤销或已过期，或复制时漏掉了某个字符。
- **如何处理**: 此 Azoth API 密钥无效（已撤销、已过期或输入有误）。请在“设置 › 访问权限”中创建新密钥。
- **由谁处理**: 工作区的所有者或管理员 · [打开相关页面](https://www.azothos.ai/dashboard/settings?section=access)

### `api_key_missing`

- **含义**: 该调用未携带 Azoth API 密钥。
- **最常见的原因**: 缺少 `Authorization` 或 `X-Azoth-API-Key` 请求头，通常是因为某个环境变量未设置。
- **如何处理**: 未发送 Azoth API 密钥。请粘贴“设置 › 访问权限”中的密钥。
- **由谁处理**: 调用方代码的开发者

### `api_key_scope_denied`

- **含义**: 该密钥有效，但受到限制——限于某些权限范围（它可调用的 API 部分）、某些连接器或某些环境——而此调用超出了这些限制。在上报时，响应中的 `dimension` 字段说明是哪项限制拒绝了它：`connector` 或 `environment`。
- **最常见的原因**: 为某一用途（例如上报或读取）创建的密钥调用了 API 的其他部分——或发送了该密钥并非为之创建的连接器或环境的事件。
- **如何处理**: 此 API 密钥仅限于某些权限范围、连接器或环境，而此调用超出了这些范围。请创建一个涵盖它的密钥，或不设这些限制（不受限）的密钥。
- **由谁处理**: 工作区的所有者或管理员 · [打开相关页面](https://www.azothos.ai/dashboard/settings?section=access)

### `api_key_name_taken`

- **含义**: 工作区中已有一个有效密钥使用了所请求的名称：同一工作区的两个有效密钥不会同名。
- **最常见的原因**: 之前以此名称创建且从未撤销的密钥——已过期的密钥在被撤销之前仍保留其名称。
- **如何处理**: 此工作区已有一个同名的有效密钥。请换一个名称，或先在“设置 › 访问权限”中撤销该密钥。
- **由谁处理**: 工作区的所有者或管理员 · [打开相关页面](https://www.azothos.ai/dashboard/settings?section=access)

### `api_key_role_denied`

- **含义**: 该密钥有效，但其角色（读取、写入或管理）低于此路由的要求：读取密钥不能调用会写入的路由，导出工作区设置需要管理密钥。
- **最常见的原因**: 以只读方式创建的密钥被用于发送数据或进行更改的代码——或该密钥的角色与集成所设定的角色不同。
- **如何处理**: 此 API 密钥的角色不允许该调用：读取密钥不能写入，某些导出需要管理密钥。请在“设置 › 访问权限”中创建具有所需角色的密钥。
- **由谁处理**: 工作区的所有者或管理员 · [打开相关页面](https://www.azothos.ai/dashboard/settings?section=access)

### `ip_not_allowed`

- **含义**: 该密钥有效，但调用来自工作区 IP 允许列表之外的地址：工作区只接受来自其所列地址的 API 密钥调用。
- **最常见的原因**: 新的服务器、云函数或网络的出站地址尚未列入——或代理更改了调用的来源地址。
- **如何处理**: 此调用来自工作区 IP 允许列表之外的地址。请从已列入的地址调用，或请所有者或管理员添加此地址。
- **由谁处理**: 工作区的所有者或管理员

### `on_behalf_of_not_allowed`

- **含义**: 此调用已被阻止：其 API 密钥不能指明调用所代表的人员。
- **最常见的原因**: 只有经所有者或管理员授权的服务密钥才能发送 X-Azoth-On-Behalf-Of。个人密钥始终代表其所有者。
- **如何处理**: 请不带该标头发送调用，或请所有者或管理员提供一个获准指明人员的服务密钥（设置 › 访问）。
- **由谁处理**: 工作区的所有者或管理员 · [打开相关页面](https://www.azothos.ai/dashboard/settings?section=access)

### `human_identity_required`

- **含义**: 此调用已被阻止：它没有指明所代表的人员。
- **最常见的原因**: 此工作区要求每次调用都归属于一个人，以便每项决策都能显示由谁作出。
- **如何处理**: 请使用您的个人 API 密钥，或使用获准指明人员的服务密钥发送 X-Azoth-On-Behalf-Of（该人员的 SCIM 标识或电子邮件）。
- **由谁处理**: 调用方代码的开发者 · [打开相关页面](https://www.azothos.ai/dashboard/settings?section=access)

### `identity_unavailable`

- **含义**: 此调用已被阻止：无法核实其所代表的人员。
- **最常见的原因**: Azoth 无法读取该密钥或工作区的归属规则；在要求归属时，它不会处理无法归属的调用。
- **如何处理**: 请稍后再试。
- **由谁处理**: Azoth，或此部署的运营方

### `invalid_on_behalf_of`

- **含义**: `X-Azoth-On-Behalf-Of` 标头不是 Azoth 能读取的人员标识。
- **最常见的原因**: 该标头为空、超过 256 个字符，或包含可见 ASCII 以外的字符。
- **如何处理**: X-Azoth-On-Behalf-Of 必须由 1 到 256 个可见 ASCII 字符组成：请发送该人员的 SCIM 标识或电子邮件。
- **由谁处理**: 调用方代码的开发者

### `key_not_bound_to_agent`

- **含义**: MCP 网关只响应绑定到某个智能体的 API 密钥——由该智能体的授权决定密钥可以调用什么——而此密钥未绑定任何智能体。
- **最常见的原因**: 使用了工作区密钥，而不是在“MCP 工具”标签页中为智能体创建的密钥；或使用了此后已解除绑定的智能体密钥。
- **如何处理**: 此 API 密钥未绑定任何智能体。请在“授权”的“MCP 工具”标签页中为该智能体创建密钥，并将该密钥提供给 MCP 客户端。
- **由谁处理**: 工作区的所有者或管理员 · [打开相关页面](https://www.azothos.ai/dashboard/mandats?tab=mcp)

### `invalid_key_identity`

- **含义**: 个人密钥始终代表其所有者：它不能再代表其他人。
- **最常见的原因**: 创建个人密钥时开启了“可指定人员”选项。
- **如何处理**: 如需指定人员，请创建开启该选项的服务密钥；个人密钥不带此选项创建。
- **由谁处理**: 工作区的所有者或管理员 · [打开相关页面](https://www.azothos.ai/dashboard/settings?section=access)
