错误码参考

本页介绍正式版已提供的 Mini App 接口及其错误处理，版本差异在对应章节注明。方法签名分别见 Client API、Node API 和 Agent API。

先区分错误形状

调用入口	读取什么	恢复依据
页面 `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 和统一工具入口共享以下错误字段：

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。

Node 统一工具入口

context.tool 的错误也采用上述 Node 调用错误形状。调用 Connector 工具时还可能保留 Host 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。

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。run() 正常返回的 status: 'error' 与 Promise 拒绝是两条不同路径，不能只写 catch 而忽略结果状态。

页面 API

页面不读取 Node 的 code / retryable / disposition。以下码值通过抛出或 Promise 拒绝时的 Error.message 返回。capabilities.has() 例外：它同步返回布尔值，见能力探测。

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。v3.1.10 中，用户取消需要重建页面的切窗确认时，update() 成功返回当前状态，mode 仍为原值，不会抛出 user_cancelled 或 busy；应检查返回的 mode。活动页面请求或订阅本身不再阻止切窗，用户确认后它们随旧页面结束而取消或清理。旧文档的 Promise 和监听器不会延续，见页面重建与确认。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。

语音转写

`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。麦克风和摄像头的标准采集错误（例如 NotAllowedError）由浏览器 API 抛出，不使用这张转写码表。

摄像头与系统通知

这两项从 MiniMax Code v3.1.9 起正式提供，使用标准浏览器 API，没有额外的宿主错误码。getUserMedia() 失败时读取浏览器异常的 name，例如 NotAllowedError。通知按标准 Notification API 处理：检查 Notification.permission 和 requestPermission() 的结果，并监听通知对象的 error 事件；实际显示还受系统通知设置影响。不要将这些结果解释为上面的语音转写错误码。声明和用法见页面设备 API。

能力探测

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

启动和运行诊断

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、端口鉴权和发布排错。

入门

了解 Mini App

开发

参考

先区分错误形状

miniapp 工具

发布诊断

Node 调用的结果与重试

Host Connector

Node 统一工具入口

Agent API

页面 API

message.append

窗口句柄

工具预授权

语音转写

摄像头与系统通知

能力探测

启动和运行诊断

​先区分错误形状

​miniapp 工具

​发布诊断

​Node 调用的结果与重试

​Host Connector

​Node 统一工具入口

​Agent API

​页面 API

​message.append

​窗口句柄

​工具预授权

​语音转写

​摄像头与系统通知

​能力探测

​启动和运行诊断

先区分错误形状

miniapp 工具

发布诊断

Node 调用的结果与重试

Host Connector

Node 统一工具入口

Agent API

页面 API

message.append

窗口句柄

工具预授权

语音转写

摄像头与系统通知

能力探测

启动和运行诊断