> ## Documentation Index
> Fetch the complete documentation index at: https://agent.minimaxi.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 错误码参考

> Mini App 页面、Node、Agent 与生命周期工具的错误形状、码值和恢复方式。

本页介绍正式版已提供的 Mini App 接口及其错误处理，版本差异在对应章节注明。方法签名分别见 [Client API](https://agent.minimaxi.com/docs/miniapp/reference/client-api.md)、[Node API](https://agent.minimaxi.com/docs/miniapp/reference/node-api.md) 和 [Agent API](https://agent.minimaxi.com/docs/miniapp/reference/agent-api.md)。

## 先区分错误形状

| 调用入口 | 读取什么 | 恢复依据 |
| - | - | - |
| 页面 `window.mcode.miniapp` | 抛出或 Promise 拒绝的 `Error.message`，使用小写码值 | 按具体方法的错误表处理；不要假设 Node 的 `code`、`reason` 或 `permissions` 会穿过页面桥接 |
| Node `context.hostConnector` / `context.tool` | `code`、`disposition`、`retryable`，以及可选的 `invocationId`、`diagnostic` | 是否已发出以 `disposition` 为准；同一个超时或取消码可能对应不同执行结果 |
| Node `context.agent` | `code`、`retryable`，`BUSY` 还可能有 `reason` | `retryable` 表示什么都没开始且可稍后重试；不要重试结果未知的回合 |
| Agent 的 `miniapp` 生命周期工具 | `{ ok: false, action, error }` | 看 `error.code`、`retryable` 和可选的 `diagnostic`；它不是页面 Promise 错误 |

跨进程调用时，不要依赖 `instanceof` 或具体 Error 子类名称。`message` 用来展示或诊断；Node 业务分支按 `code` 判断。

## miniapp 工具

本节列出 Agent 执行 `init`、`publish`、`open`、`inspect`、`restart` 和 `stop` 时的工具错误，与 Node `context.tool` 的错误不同。

| `error.code` | 含义与处理 |
| - | - |
| `INVALID_ARGUMENTS` | action 或参数组合不合法；修正参数，不原样重试 |
| `NOT_FOUND` | 找不到目标 Mini App；核对 `pluginId` 和安装状态 |
| `NOT_ENABLED` | 插件未启用；先启用插件 |
| `PLUGIN_ALREADY_EXISTS` | 同名插件已存在；查看 `diagnostic`，不能通过本地发布覆盖官方包 |
| `BUSY` | 查看 `busyReason`：`operation_busy` 为同一插件操作未完成；`capacity_busy` 为 3 个运行名额已满，需要先释放名额 |
| `SERVICE_RESTARTED` | 操作期间服务已切换代次；刷新状态后按 `retryable` 决定重试 |
| `PREPARATION_FAILED` | 包、清单、安装或启动准备失败；按下面的 `diagnostic.recovery` 和 `hint` 处理 |
| `RUNTIME_FAILED` | 运行时未能完成操作；结合 `runtimeError` 和 `inspect` 定位，不把它当成单一根因 |
| `OPEN_UNAVAILABLE` | 当前宿主没有提供打开页面的界面 |
| `INTERNAL_ERROR` | 宿主内部失败；可能带 `diagnosticId`、`lastGoodAvailable`，保留诊断信息，不原样重试 |
| `CANCELLED` | 操作已取消；由用户或业务决定是否重新发起 |

`error.retryable` 是宿主给出的恢复提示。`capacity_busy` 不会因为原样重试而释放名额；`PREPARATION_FAILED` 即使恢复动作为 `retry`，也要先完成其提示的条件。

### 发布诊断

`error.diagnostic` 的形状为 `{ stage, reasonCode, recovery, hint }`。`stage` 为 `workspace`、`runtime`、`mcp`、`connector` 或 `host`；`recovery` 为 `edit_workspace`、`retry` 或 `user_action`。下面列的是公开发布诊断的 `reasonCode`，不能把它们当作同层的 `error.code`。

| `reasonCode` | 要检查什么 |
| - | - |
| `OFFICIAL_PLUGIN_READ_ONLY` | 官方插件不能本地修改或重新发布；对应 `PLUGIN_ALREADY_EXISTS` |
| `MINIAPP_WORKSPACE_CANDIDATE_MISSING` | 当前工作区没有待发布的包；成品目录需通过 `sourcePath` 提供 |
| `MINIAPP_SOURCE_UNAVAILABLE`、`MINIAPP_SOURCE_INVALID` | 指定目录是否可读、是否为完整成品包 |
| `MINIAPP_SOURCE_IDENTITY_MISMATCH`、`MINIAPP_SOURCE_OVERLAP` | 包身份是否匹配 `pluginId`，源目录是否与安装目录重叠 |
| `WORKSPACE_PLUGIN_INVALID`、`MINIAPP_REFERENCE_INVALID` | `plugin.json` 和 `package.json` 的声明入口 |
| `MINIAPP_MANIFEST_INVALID`、`MINIAPP_MANIFEST_FIELD_UNSUPPORTED` | manifest 格式、schema 和宿主是否认识所用字段 |
| `MINIAPP_ARTIFACTS_INVALID`、`MINIAPP_RUNTIME_INVALID`、`MINIAPP_RUNTIME_ENTRY_INVALID` | 载荷目录、进程运行方式和入口覆盖范围 |
| `MINIAPP_SURFACE_INVALID`、`MINIAPP_MCP_ENDPOINTS_INVALID` | 页面路由、窗口字段和 MCP endpoint 声明 |
| `MINIAPP_CONNECTOR_ACCESS_INVALID`、`MINIAPP_AGENT_ACCESS_INVALID`、`MINIAPP_TOOL_ACCESS_INVALID`、`MINIAPP_DEVICE_ACCESS_INVALID` | 权限项名称、取值和宿主版本是否支持 |
| `MINIAPP_AGENT_CONCURRENCY_INVALID` | 并发数是否为 1–32 的整数 |
| `MINIAPP_ENGINES_INVALID` | `engines.mcode` 是否使用唯一支持的 `>=MAJOR.MINOR.PATCH` 格式 |
| `MINIAPP_HOST_TOO_OLD` | 宿主是否满足 `engines.mcode`；升级宿主或核实包是否确需该下限 |
| `WORKSPACE_CHANGED`、`WORKSPACE_INSTALL_FAILED` | 准备时是否还在改文件，以及本地安装冲突或文件访问失败 |
| `RUNTIME_START_FAILED`、`RUNTIME_START_EXPORT_MISSING`、`RUNTIME_LIFECYCLE_INVALID`、`RUNTIME_NOT_READY` | Node 入口加载、`start` 导出、返回值与就绪过程 |
| `MCP_INVENTORY_INVALID`、`MCP_INVENTORY_MISMATCH`、`MCP_PUBLICATION_INVALID` | MCP 工具清单、摘要和安全发布是否一致 |
| `MCP_ENDPOINT_UNREACHABLE`、`MCP_PROTOCOL_INVALID` | MCP endpoint 是否已启动并返回合法协议响应 |
| `HOST_CONNECTOR_UNAVAILABLE`、`HOST_CONNECTOR_PROTOCOL_INVALID` | 宿主桥接是否可用，以及是否仅通过公开 Connector API 调用 |
| `HOST_CAPACITY_UNAVAILABLE` | 是否需要停止一个未使用的 Mini App 或等待当前操作完成 |

## Node 调用的结果与重试

Host Connector 和统一工具入口共享以下错误字段：

```typescript theme={null}
interface HostCallError extends Error {
  code: string; // 公开码值见下表
  disposition: 'not_dispatched' | 'provider_reported' | 'unknown_after_dispatch';
  retryable: boolean;
  invocationId?: string;
  diagnostic?: {
    issues: { path: string; constraint: string; limit?: number }[];
  };
}
```

* `not_dispatched`：没有发给目标；修正原因后再考虑重试。
* `provider_reported`：服务已经返回失败。依据该服务的业务结果处理，不能因此推断写操作绝对没有发生。
* `unknown_after_dispatch`：调用可能已执行。先读取业务状态核对，不能仅因 `retryable` 或错误名称而重复写入。
* `invocationId` 用于关联同一次调用，可能缺省。`diagnostic.issues` 只提供安全的字段路径、约束和上限，不包含用户参数值。

## Host Connector

| Node `code` | 含义与处理 |
| - | - |
| `TOOL_REF_STALE` | 引用已过期；重新 `list()`，不要自行构造 `toolRef` |
| `SERVICE_RESTARTED` | 发出前服务已重启；重新列出工具并核对当前状态 |
| `REQUEST_CANCELLED` | 请求被取消；仍检查 `disposition`，不要仅凭名称推断未执行 |
| `CONNECTOR_TIMEOUT` | 发出前等待超时；若发出后失去确认，会以结果未知处理 |
| `INVALID_ARGUMENTS` | 本地输入无效、参数不符合 schema，或请求超过 256 KiB JSON 上限；存在时查看 `diagnostic.issues`，参数过大时先缩小 |
| `CONNECTOR_NOT_PERMITTED` | 用户关闭了这个 provider 的权限；没有发出，需用户重新开启 |
| `CONNECTOR_PROVIDER_ERROR` | 第三方服务报告失败；不一定是授权失效 |
| `CONNECTOR_UNAVAILABLE` | 当前代次的 Connector 不可用；是否可重试看 `retryable` |
| `CONNECTOR_OUTCOME_UNKNOWN` | 发出后丢失确认，包括发出后的传输中断、超时或取消；先核对业务状态 |

接口与返回结构见 [Node API](https://agent.minimaxi.com/docs/miniapp/reference/node-api.md#connector)。

## Node 统一工具入口

`context.tool` 的错误也采用上述 Node 调用错误形状。调用 Connector 工具时还可能保留 [Host Connector 错误码](https://agent.minimaxi.com/docs/miniapp/reference/errors.md#connector)。

| Node `code` | 含义与处理 |
| - | - |
| `INVALID_ARGUMENTS` | 工具名、JSON 参数、授权请求列表无效，或请求超过 256 KiB JSON 上限；从 `list()` 重新确认工具名和 schema，参数过大时先缩小。`diagnostic` 可能缺省 |
| `TOOL_NOT_PERMITTED` | 没有调用授权、`tool:call` 关闭、规则为 `deny`，或用户拒绝本次调用 |
| `TOOL_APPROVAL_REQUIRED` | 需要确认，但当前无人可回答；在可交互的宿主界面发起授权 |
| `TOOL_UNAVAILABLE` | 当前进程代次或工具通道不可用 |
| `TOOL_REF_STALE` | 该运行时工具名不再可用；重新 `list()` |
| `TOOL_TIMEOUT` | 等待审批或执行阶段超时；`disposition` 区分尚未发出与发出后结果未知 |
| `TOOL_RESULT_TOO_LARGE` | 结果超过响应帧上限；调用可能已经执行，检查 `disposition`，缩小业务结果 |
| `TOOL_OUTCOME_UNKNOWN` | 请求发出后，结果无法确认或无法安全表示为 JSON；先核对业务状态 |
| `MCP_SERVER_UNAVAILABLE` | MCP 服务器不可用；查看 `retryable`，恢复服务器后再试 |
| `REQUEST_CANCELLED` | 调用被取消；发出后取消不保证撤回目标操作 |
| `SERVICE_RESTARTED` | 子进程与宿主通道被替换；重新获取工具和状态 |

Node `request(names)` 在无人审批时以 `TOOL_APPROVAL_REQUIRED` 拒绝，并在错误对象附加 `permissions` 权限快照；这个字段只用于界面提示。仅关闭 `tool:call` 时，`request()` 成功返回各名称为 `deny` 的快照，不弹框；这与 `call()` 被拒绝不同。MCP 工具正常返回的 `isError: true` 是工具报告业务失败，不是 Promise 拒绝。

接口与结果联合类型见 [Node API](https://agent.minimaxi.com/docs/miniapp/reference/node-api.md#tools)。

## Agent API

Node 读取 `error.code`、`error.retryable`，`BUSY` 还带可能的 `error.reason`。页面读取 `Error.message`。下表列出宿主对运行时错误的映射，不能直接将 Node 码值转成小写。

| Node `code` | 页面 `message` | 含义与处理 |
| - | - | - |
| `NOT_PERMITTED` | `not_permitted` | 未声明所需的 `session.run` / `session.read`、开关关闭，或当前操作没有所需权限；两项授权互不包含 |
| `BUSY` | `busy` | 会话忙、队列满、启动频率受限或观察订阅已满；Node 按下面的 `reason` 区分 |
| `SESSION_NOT_FOUND` | `session_not_found` | 会话不存在、归属不允许或不可见；不要尝试绕过会话归属 |
| `INVALID_ARGUMENTS` | `invalid_request` | 参数、模型、目标组合或问卷答案不合法 |
| `AGENT_UNAVAILABLE` | `runtime_unavailable` | 未能开始操作，或读取/观察当前不可用；按 Node `retryable` 决定是否稍后再试 |
| `REQUEST_CANCELLED` | `cancelled` | 发出前请求被取消；回合已经启动后的取消通常以结果 `status: 'aborted'` 结束 |
| `AGENT_OUTCOME_UNKNOWN` | `result_unknown` | 回合或写操作可能已经发生，不要自动重发 |
| `REQUEST_NOT_FOUND` | `request_not_found` | 审批或问卷不存在、已处理或不属于当前可回答的请求 |

Node 的 `BUSY.reason` 有 `session_busy`、`queue_full`、`rate_limited`、`observer_limit` 四种。`whenBusy` 解决目标会话忙时的跟进，不会取消其他限额。页面还可能因重复使用在途 `requestId` 而收到 `busy`；不要依赖页面错误上附加 `reason`，桥接只保证错误消息。

页面传输失败时，各方法的错误码也有区别：`run`、`answer`、`reply`、`open`、`models`、`agents`、`create` 的桥接失败可能返回 `result_unknown`；`observe`、`sessions`、`session` 的桥接失败返回 `runtime_unavailable`。因此不能把所有只读方法的传输失败归为同一个码。

接口、返回的 `error` 字段和事件见 [Agent API](https://agent.minimaxi.com/docs/miniapp/reference/agent-api.md)。`run()` 正常返回的 `status: 'error'` 与 Promise 拒绝是两条不同路径，不能只写 `catch` 而忽略结果状态。

## 页面 API

页面不读取 Node 的 `code` / `retryable` / `disposition`。以下码值通过抛出或 Promise 拒绝时的 `Error.message` 返回。`capabilities.has()` 例外：它同步返回布尔值，见[能力探测](https://agent.minimaxi.com/docs/miniapp/reference/errors.md#capabilities)。

### message.append

| `message` | 含义与处理 |
| - | - |
| `user_cancelled` | 用户取消确认；没有追加，不自动再弹确认 |
| `invalid_request` | 参数不是字符串或请求不合法 |
| `text_too_large` | 超过 100,000 个 UTF-16 码元；缩短文本 |
| `not_allowed` | 当前页面身份或操作不允许 |
| `target_unavailable` | 目标会话不可写、已删除或当前不可用；不回退到其他草稿 |
| `result_unknown` | 内容可能已追加；先看目标输入框，不自动重发 |

### 窗口句柄

下表说明 v3.1.10 的窗口行为。v3.1.9 的差异见表后说明。

| `message` | 含义与处理 |
| - | - |
| `invalid_request` | patch 字段、数值范围或回调类型不合法 |
| `inline_mode` | 当前在文件面板，操作要求独立窗口模式 |
| `not_permitted` | 缺少用户手势、请求超出 manifest 允许的窗口能力，或更新后未在同一显示器工作区横纵方向各保留至少 40 px 的可见部分 |
| `busy` | 同一页面已有切窗确认、模式切换或重建，或同一宿主窗口正在确认另一个 Mini App；等待当前操作结束 |
| `result_unknown` | 页面身份、响应或传输无法确认；先读 `getState()` 核对 |

`not_found` 是宿主内部窗口响应，不作为页面错误码暴露；页面收到 `result_unknown`。方法和可写字段见 [Client API](https://agent.minimaxi.com/docs/miniapp/reference/client-api.md#window)。

v3.1.10 中，用户取消需要重建页面的切窗确认时，`update()` 成功返回当前状态，`mode` 仍为原值，不会抛出 `user_cancelled` 或 `busy`；应检查返回的 `mode`。活动页面请求或订阅本身不再阻止切窗，用户确认后它们随旧页面结束而取消或清理。旧文档的 Promise 和监听器不会延续，见[页面重建与确认](https://agent.minimaxi.com/docs/miniapp/reference/client-api.md#window-reload)。

v3.1.9 中，活动请求、观察订阅、权限提示或采集也可能让切窗返回 `busy`；已获麦克风授权的页面另有切窗确认，用户取消也返回 `busy`。不要把 v3.1.10 的取消规则用于这些旧宿主。

### 工具预授权

| `message` | 含义与处理 |
| - | - |
| `invalid_request` | 不是用户手势调用，或名称列表不是 1–10 个不同的合法运行时工具名 |
| `not_permitted` | 调用页面身份或当前权限不允许该请求 |
| `approval_required` | 有工具需要确认，但当前无法显示宿主审批 |
| `runtime_unavailable` | 没有可用的 Node 工具会话，或宿主工具通道不可用 |
| `result_unknown` | 响应、超时或桥接结果未知；重新获取当前权限，不把旧快照当授权凭据 |

页面 `tool.request()` 仅关闭 `tool:call` 时成功返回全 `deny`，不会抛 `not_permitted`。与 Node 的同名方法不同，页面失败只抛码值；即使宿主响应带权限快照，也不要依赖 `error.permissions`。见 [Client API](https://agent.minimaxi.com/docs/miniapp/reference/client-api.md#tool-request)。

### 语音转写

| `message` | 含义与处理 |
| - | - |
| `invalid_request` | 输入、精确格式、样本字节或容器类型不合法；先转成要求的 PCM |
| `not_permitted` | 未声明麦克风、开关关闭或不是受管理的 Mini App 页面 |
| `audio_too_large` | 音频超过 16,000,000 字节或宿主转写时长上限 |
| `busy` | 本插件已有一个转写正在处理；等待它结束 |
| `runtime_unavailable` | 宿主语音识别未启用、未登录或会话无法建立 |
| `transcription_failed` | 上游失败、达到转写时限或页面生命周期结束；转写时限目前为 180 秒 |
| `result_unknown` | 响应或桥接失败；没有可供页面恢复原请求的句柄 |

转写只返回文本，不取消或停止页面自己的采集流。格式、结果与 `onPartial` 见 [Client API](https://agent.minimaxi.com/docs/miniapp/reference/client-api.md#speech)。麦克风和摄像头的标准采集错误（例如 `NotAllowedError`）由浏览器 API 抛出，不使用这张转写码表。

### 摄像头与系统通知

这两项从 MiniMax Code v3.1.9 起正式提供，使用标准浏览器 API，没有额外的宿主错误码。

`getUserMedia()` 失败时读取浏览器异常的 `name`，例如 `NotAllowedError`。通知按标准 `Notification` API 处理：检查 `Notification.permission` 和 `requestPermission()` 的结果，并监听通知对象的 `error` 事件；实际显示还受系统通知设置影响。不要将这些结果解释为上面的语音转写错误码。声明和用法见[页面设备 API](https://agent.minimaxi.com/docs/miniapp/authors/client-api.md#devices)。

### 能力探测

`capabilities.has(name)` 同步返回 `boolean`，未知名称为 `false`，没有宿主错误码或 Promise 拒绝。旧宿主可能没有这个对象，先使用可选链检测；直接调用不存在的对象会产生 JavaScript 错误，不是 Mini App 的权限错误。能力名称和适用端见 [Client API](https://agent.minimaxi.com/docs/miniapp/reference/client-api.md#capabilities)。

## 启动和运行诊断

`inspect` 的 `diagnostics.failure.code`、`diagnostics.run.failure.code` 和日志中的 `code` 用于定位运行阶段。它们与前面的工具 `error.code`、`diagnostic.reasonCode` 属于不同层，不能互换。例如底层 `READINESS_TIMEOUT` 可帮助判断 Node 监听/就绪问题，对外发布诊断则使用 `RUNTIME_NOT_READY`。

先检查入口是否导出 `start(context)`、是否用 `node:http` 监听分配端口、是否在监听和路由安装完成后返回。退出状态、时间或失败信息缺失时，按“未知”处理，不要仅凭诊断名称推断进程已经退出。契约与处理步骤见 [Node API](https://agent.minimaxi.com/docs/miniapp/reference/node-api.md#lifecycle)、[端口鉴权](https://agent.minimaxi.com/docs/miniapp/authors/node-runtime.md#auth)和[发布排错](https://agent.minimaxi.com/docs/miniapp/authors/publish.md)。