Errors - LI.FI

失败的 POST /compose 会返回一个结构化的 ComposeError：

interface ComposeError {
  readonly kind: ComposeErrorKind;
  readonly message: string;
  readonly path?: string;
}

kind 是下方联合类型中的判别标识（discriminator）。message 是人类可读的描述。path（当存在时）指明 Flow JSON 中触发该错误的字段。

Error kinds

随 @lifi/compose-spec 一起发布的完整 ComposeErrorKind 联合类型：

Kind	HTTP	When
`decode_error`	400	Flow JSON 格式错误，或未通过针对 wire schema 的结构校验。
`validation_error`	400	Port 绑定、ref 目标、op 或 guard 名称，或其他语义检查失败。
`linearity_error`	400	某个资源被多于一个下游调用绑定为消费型输入。
`resolve_error`	500	服务端在依据 manifest 解析 flow 时出错。通常重试是安全的。
`preparation_error`	422	某个需要链上解析的金额（例如 vault 份额价格）无法确定，读取返回 `0` 或被 revert。
`no_route_error`	404	路由层无法在所请求的链上为某个 `lifi.zap` 的 `resourceOut` 目标找到路径。
`lowering_error`	500	服务端在将高层 op 降级为 VM 字节码时出错。通常重试是安全的。
`simulation_error`	500	模拟期间的传输或基础设施故障。通常重试是安全的。
`simulation_setup_error`	422	模拟器无法建立模拟（例如链的 RPC 不可达）。
`simulation_revert`	422	模拟交易在链上 revert。参见下方 Allow-revert mode。
`guard_error`	422	给定模拟出的值，某个 guard 断言在执行时将会失败。请放宽容差或检查报价。
`compilation_error`	500	服务端在生成最终 calldata 时出错。通常重试是安全的。
`verification_error`	500	编译产物未通过服务的策略校验（合约白名单、转移模式、指令上限）。
`price_impact_exceeded`	422	聚合的美元价格影响超过了 `run.maxPriceImpactBps` 中传入的上限。请降低预期或接受更高的影响。
`provider_error`	422	上游提供方（报价或路由）在解析 flow 时返回了错误。
`resolution_rejected`	422	协议明确拒绝了请求，例如许可制金库的授权或资格检查失败。重试相同请求无法成功。
`resolution_error`	503	无法从协议获取流程所需的数据，例如存入授权。请按退避策略重试。
`subgraph_simulation_revert`	422	模拟 flow 的某一段在链上 revert。
`continuation_error`	400	多步续接（continuation）请求无法恢复（例如所引用的前一步骤缺失或无效）。
`fee_resolution_error`	422	该 flow 的集成方费用无法解析。
`fee_resolution_unavailable`	503	费用解析暂时不可用。请按退避策略重试。
`flashloan_unauthorized`	422	请求了某个闪电贷步骤，但该步骤未获此集成的授权。

Recovery hints

400 类 kind 表示调用方必须修复的问题：Flow JSON、ref 语法或输入绑定。重新提交相同的请求会以相同的方式失败。
404（no_route_error） 表示路由图中没有匹配所请求链上输入/输出对的边。请查阅 Supported Protocols & Chains 了解当前覆盖范围；目标 vault 可能尚未成为一条路由边。
422 类 kind 是运行时 / 数据问题。请调整容差（slippage、maxPriceImpactBps）、等待链上状态稳定，或将错误呈现给你的用户。
500 类 kind 是服务端问题。请按退避策略重试；若错误持续存在，请联系 LI.FI。

Allow-revert mode

当 run.simulationPolicy 为 "allow-revert" 时，simulation_revert 不再使调用失败。相反，响应会返回已编译的 transactionRequest，同时在部分结果的 simulationRevert 字段上返回 revert 诊断信息（HTTP 206）。当你希望将 revert 原因呈现给用户而非隐藏时，请使用此模式。参见 Guards 了解 guard_error 如何产生，参见 Execution Model 了解每种错误 kind 在编译流水线中的起源。

See also

Execution Model —— 发出每种错误 kind 的流水线阶段。
Guards —— guard_error 背后的观测到断言（observation-to-assertion）机制。
Flow wire format —— POST /compose 返回的请求与响应结构。