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

# Errors

> ComposeError kinds, HTTP status mapping, and recovery hints.

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

```ts theme={"system"}
interface ComposeError {
  readonly kind: ComposeErrorKind;
  readonly message: string;
  readonly path?: string;
}
```

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

## Error kinds

随 [`@lifi/compose-spec`](https://www.npmjs.com/package/@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 时返回了错误。                               |
| `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](/composer/protocols-and-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](/composer/composer-api/concepts/simulation-and-guards) 了解 `guard_error` 如何产生，参见 [Execution Model](/composer/composer-api/concepts/execution-model) 了解每种错误 kind 在编译流水线中的起源。

## See also

* [Execution Model](/composer/composer-api/concepts/execution-model) —— 发出每种错误 kind 的流水线阶段。
* [Guards](/composer/composer-api/concepts/simulation-and-guards) —— `guard_error` 背后的观测到断言（observation-to-assertion）机制。
* [Flow wire format](/composer/composer-api/reference/flow-wire-format) —— `POST /compose` 返回的请求与响应结构。