错误模型

错误先分类，再决定怎么处理：是调用方改参数就能好（契约错）、是正常业务结果（业务错）、还是等一会儿重试（可重试错）。判断依据是 code，不是 message 文案。

本文按 SDK / 工具链 1.0.0、后端契约 1.1.0 说明失败通道；可重试分类不承诺目标环境自动恢复，也不保证再次调用没有重复副作用。

后端脚本：抛错三分类

抛错时带上 code，平台按错误码决定处置：

分类	错误码	平台行为	用法
契约错	`INVALID_ARGUMENT`、`UNKNOWN_FIELD`、`UNKNOWN_ENTITY`、`INVALID_FILTER`、`EMPTY_FILTER`、`TYPE_MISMATCH`、`LIMIT_EXCEEDED`、`PERMISSION_DENIED`	HTTP 400 + `40006`；消息丢弃，不重投	参数缺失、格式不对、权限不够——调用方改了就能好
业务结果	`NOT_FOUND`、`DUPLICATE`、`CONFLICT`	HTTP 200 + `20001`；不算故障	查无此记录、重复提交、状态冲突
可重试	`TIMEOUT`、`UNAVAILABLE`、`DEADLOCK`、`STORAGE_ERROR`，以及其他认不出的错误码、普通 `Error`	HTTP 503 + `50301`；是否再次请求由调用方决定	网络抖动、下游暂不可用

没写 code 的 throw new Error(...) 落入可重试档；认不出的错误码也会在错误文案里点名提示。

各路径的处置差异：

分类	HTTP 接口处理函数	事件消费	流程
契约错	400 / `40006`	丢弃 / 死信	步骤失败，不重试
业务结果	200 / `20001`	确认，不重投	步骤失败，不重试
可重试	503 / `50301`；平台不自动重发请求	每次投递按部署配置有界尝试，耗尽后丢弃	按动作和步骤的有效策略重试

事件最大尝试次数包含首次执行，不是固定“重试 3 次”。丢弃（Discard）只有在队列配置了死信保存时才进入死信队列，恢复后的人工重放也不是自动保证。消费方并发与聚合处置见事件消费参考；流程的尝试次数、退避和整步重跑边界见流程编排语言。

返回值的错误通道不能按入口类推：事件入口顶层失败信封会参与错误分类；HTTP 接口处理函数和流程脚本不会自动提升返回的失败信封。能力返回失败时，先按该方法的信封或异常约定处理，需要让入口失败则显式抛出错误，不能吞掉后显示成功。

统一信封 {code, message, data}，成功判据是 HTTP 2xx 且 code === 0；失败没有 data。完整码表见错误码，常用的：

跨隔离环境传回来的错误长这样。用 error.code 或 isPluginError(error) 判断，不要依赖 instanceof（跨边界不可靠）：

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

常用错误码（完整列表见 SDK 导出的 PLUGIN_ERROR_CODES 常量）：

错误码	场景	处理
`MANIFEST_INVALID` / `PLUGIN_ENTRY_INVALID`	清单或入口不合法	修正后重新构建
`CAPABILITY_NOT_AVAILABLE`	能力未授权或宿主未提供	降级，不要当网络错误重试
`PLUGIN_GATEWAY_ERROR`	网关返回业务错误	捕获异常并核对其结构化详情中的业务码，不把失败当普通成功返回值
`PLUGIN_NETWORK_BLOCKED`	`ctx.apiCall()` 的 endpoint、method、GET 请求体、超时或幂等键不合法	修正调用参数；它不是入口原生 `fetch` / XHR / WebSocket 护栏拦截的稳定错误码
`VIEW_NOT_DECLARED` / `VIEW_LOAD_FAILED`	界面未声明 / 加载失败	补清单 `views` / 检查构建产物
`PLUGIN_VALUE_INVALID`	跨边界传了不可克隆的值	只传 `PluginValue`
`STORAGE_QUOTA_EXCEEDED`	存储超配额	清理数据，重试无效
`TIMEOUT`	请求超时	结果未知：先查状态，再用同一幂等键决定重试
`HOST_RUNTIME_DISPOSED` / `RUNTIME_UNRESPONSIVE`	运行时已停用 / 无响应	停止使用旧上下文和句柄

前端错误码只增不改；删除或改义属于破坏性协议变更。

前端 TIMEOUT：请求可能已送达。先按业务 ID 查权威状态，再决定是否用同一幂等键重试。

后端 50401：信号投递在超时内没返回。用相同 Idempotency-Key 重试，或先查 awaitingSignal。

accepted（受理）不等于设备执行成功；最终结果以任务、设备或业务记录的权威状态为准。

错误 message 会进浏览器诊断、服务日志和流程历史。只写错误码、字段名、插件/脚本/流程 ID 和固定文案；不要写 token、请求体、SQL、签名 URL 或配置值。

现象	原因与处理
相同错误反复出现	核对错误分类、实际尝试次数及事件是否重新投递；不要仅凭重复日志推断无限重试
返回 200 但业务是失败的	`20001` 是业务结果不是成功；判成功只能看 `code === 0`
超时后重试造成重复写入	重试没带幂等键；补 `Idempotency-Key`，服务端用 `stableId` 去重
`instanceof PluginError` 判断失效	跨隔离环境不可靠；改用 `error.code` 或 `isPluginError()`