错误码

按端分三块：前端运行时错误码（SDK 常量）、后端 HTTP 业务码、后端脚本抛错分类。判断一律看 code，不要解析 message 文案。

前端异常（`PluginError`）

跨隔离环境传回的错误形状；用 error.code 或 isPluginError(error) 判断，不要依赖 instanceof：

import type { PluginErrorCode, PluginValue } from 'fh2-plugin-sdk'

interface PluginErrorShape {
  readonly code: PluginErrorCode
  readonly message: string
  readonly pluginId?: string
  readonly hostId?: string
  readonly detail?: PluginValue
}

常用错误码：

错误码	发生位置	调用方动作
`MANIFEST_INVALID`、`ENGINE_INCOMPATIBLE`、`PLUGIN_ENTRY_INVALID`	安装 / 激活	修正清单、入口或运行环境后重新构建
`EXTENSION_POINT_NOT_FOUND`、`EXTENSION_DECLARATION_INVALID`、`EXTENSION_IMPLEMENTATION_INVALID`	扩展声明或贡献	对照扩展点 ID、清单静态字段与 `contribute()` 的状态/方法
`REGISTRATION_CONFLICT`、`POINT_CONSUMER_CONFLICT`	重复注册	保证插件内 ID、界面处理函数、跨宿主通信服务提供方唯一
`CAPABILITY_NOT_AVAILABLE`、`CAPABILITY_CONTRACT_INVALID`、`CAPABILITY_REALM_MISMATCH`	能力获取	`get()` 为 `undefined` 时降级；环境限制不能靠重试绕过
`SERVICE_CONTRACT_INVALID`、`SERVICE_UNAVAILABLE`	跨宿主通信服务	修正 `PluginValue` 契约；提供方未注册时等待或降级
`VIEW_NOT_DECLARED`、`VIEW_LOAD_FAILED`、`VIEW_CONTRIBUTION_ALREADY_MOUNTED`	界面	在清单 `views` 声明资源；检查默认导出与挂载生命周期
`HOST_RUNTIME_DISPOSED`、`RUNTIME_UNRESPONSIVE`、`RESOURCE_LEAK`	生命周期	停止使用旧上下文、句柄、定时器和订阅
`PLUGIN_VALUE_INVALID`、`CONFIG_VALUE_INVALID`	跨边界传值 / 配置	只传可克隆的 `PluginValue`；非法配置会回退默认值
`STORAGE_QUOTA_EXCEEDED`	键值 / Blob 存储	删除不再使用的数据；重试无法突破配额
`PLUGIN_NETWORK_BLOCKED`	`ctx.apiCall()` 参数校验	核对 endpoint、method、GET 请求体、超时及幂等键；业务路径用单 `/`，绝对 HTTP(S) URL 另需白名单。它不是裸网络 Guard 拦截的稳定错误码
`PLUGIN_GATEWAY_ERROR`	受管请求的网关响应	检查 `detail.gatewayCode`、`gatewayMessage` 与 HTTP 状态，不把业务失败当成功
`TIMEOUT`	请求或异步操作	副作用可能已送达；先按业务 ID 查状态，再用同一幂等键决定重试

完整错误码列表见 SDK 1.0.0 导出的 PLUGIN_ERROR_CODES 常量。错误码只增不改；删除或改义属于破坏性协议变更。

后端 HTTP 业务码

已部署后端服务的接口返回 {code, message, data?}。成功判据：HTTP 2xx 且 code === 0；该服务的失败响应没有 data。下表描述该服务，不是本地模拟器或所有网关的 HTTP 状态表；直接后端服务的访问凭据与插件网关 Token 不可互换。

前端经 ctx.apiCall('/plugin/invoke', ...) 调用时，非零数字业务码会抛 PLUGIN_GATEWAY_ERROR；数字码在 error.detail.gatewayCode，消息在 gatewayMessage，HTTP 状态在 httpStatus。不要把 PluginError.code 当成后端业务码，也不要在普通返回值上处理失败。

HTTP	业务码	含义	调用方动作
200	`0`	成功	读 `data`
200	`20001`	插件业务结果（如 `NOT_FOUND`）	不是成功；按业务处理，不要盲目重试
400	`40001`	JSON / 参数或业务 ID 非法	修改请求
400	`40002`	未声明的流程信号	用流程 `await`/`callback` 声明的信号名
400	`40003`	信号数据缺必填键	补齐 `provides` 声明的键
400	`40004`	信号数据类型错误	按声明修正类型
400	`40005`	信号数据含未声明键	移除字段，或流程显式设 `extraKeys: "allow"`
400	`40006`	插件契约错	修正 `{pluginId, handler, input}` 或脚本入参
401	`40101`	未授权（token 缺失或错误）	重新取得凭据；不要记录 token 值
403	`40301`	流程未声明 `api` 触发器	改用允许的触发方式
404	`40401`	流程不存在	核对流程名或路径
404	`40402`	流程实例不存在	核对完整实例 ID
405	`40501`	HTTP 方法错误	按响应 `Allow` 头改用正确方法
409	`40901`	当前未等待该信号	查询 `awaitingSignal` 后再投递
409	`40902`	中断信号不在当前作用域	等流程进入声明的中断范围
409	`40903`	同一信号重复投递	视为已受理，查询流程状态
500	`50001`	工作流引擎调用失败	按监控与幂等性决定重试
503	`50301`	插件暂不可用（可重试）	带稳定 `Idempotency-Key` 退避重试
504	`50401`	信号投递超时	结果未知；用相同幂等键重试或先查实例状态

本地 HTTP 错误

Toolchain 1.0.0 当前 dev 的后端调用与事件辅助接口也返回数字错误信封：{code, message, data: null}。数字码按脚本错误分类映射，原错误标识保留在 message，但 HTTP 状态保留本地行为，不改成上表的部署服务状态。

本地错误或请求	HTTP	数字 `code`
`INVALID_ARGUMENT`，或 `stableId` 缺键的 `IDEMPOTENCY_KEY_REQUIRED`	400	`40006`
`PERMISSION_DENIED`	403	`40006`
`PLUGIN_NOT_FOUND` / `HANDLER_NOT_FOUND` / `EVENT_HANDLER_NOT_FOUND`	404	`40006`
`NOT_FOUND`	404	`20001`
`CONFLICT`；`DUPLICATE`	409；400	`20001`
未分类字符串错误（如 `BRIDGE_FAILED`）；普通脚本异常	400；500	`50301`
`RUNTIME_CLOSED` / `BACKEND_DIST_MISSING`	503	`50301`
invoke 缺少有效插件 Token	401	`10005`

BRIDGE_FAILED 即使 HTTP 为 400 也属于未分类的可重试错误，不是契约错；HTTP 400 不能单独决定业务分类。invoke 多余顶层字段当前仍可能被接受，不能据此证明部署服务的 40001 校验。更多差异见后端调试的已知限制。

后端脚本抛错：三分类

脚本里主动抛错时带上字符串 code，平台按错误码三分类处置；这与 HTTP 信封的数字 code 是两层。下表 HTTP 映射适用于已部署后端服务，本地 HTTP 状态见上一节：

分类	错误码示例	HTTP 映射	流程 / 事件处置
契约错	`INVALID_ARGUMENT`、`UNKNOWN_FIELD`、`UNKNOWN_ENTITY`、`INVALID_FILTER`、`EMPTY_FILTER`、`TYPE_MISMATCH`、`LIMIT_EXCEEDED`、`PERMISSION_DENIED`	400 / `40006`	步骤失败不重试；事件丢弃/死信
业务结果	`NOT_FOUND`、`DUPLICATE`、`CONFLICT`	200 / `20001`	步骤失败不重试；事件确认不重投
可重试	`TIMEOUT`、`UNAVAILABLE`、`DEADLOCK`、`STORAGE_ERROR`，以及认不出的错误码、普通 `Error`	503 / `50301`	按步骤 / 事件重试策略处理

注意：

没写 code 的 throw new Error(...) 落入可重试档。

accepted、通知已投递、请求超时都不等于设备或业务终态；对飞行、设备、任务和写操作，必须用业务 ID 查询权威状态。

常见问题

现象	原因与处理
抛错被反复重试	错误码认不出（落可重试档）；改用三分类里的标准错误码
HTTP 200 却当失败处理	`20001` 是业务结果；成功判据只有 `code === 0`
前端 `instanceof` 判断错误类型失效	跨隔离环境不可靠；用 `error.code` 判断
想看前端全部错误码	见 SDK `PLUGIN_ERROR_CODES` 常量；本页只列常用项

前端异常（PluginError）#

后端 HTTP 业务码#

本地 HTTP 错误#

后端脚本抛错：三分类#

常见问题#

前端异常（`PluginError`）

后端 HTTP 业务码

本地 HTTP 错误

后端脚本抛错：三分类

常见问题