> ## 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.

A failed `POST /compose` returns a structured `ComposeError`:

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

`kind` is the discriminator from the union below. `message` is human-readable. `path` (when present) names the field in the Flow JSON that triggered the error.

## Error kinds

The full `ComposeErrorKind` union shipped with [`@lifi/compose-spec`](https://www.npmjs.com/package/@lifi/compose-spec):

| Kind                         | HTTP | When                                                                                                                                        |
| ---------------------------- | ---- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `decode_error`               | 400  | Flow JSON is malformed or fails shape validation against the wire schema.                                                                   |
| `validation_error`           | 400  | Port bindings, ref targets, op or guard names, or other semantic checks fail.                                                               |
| `linearity_error`            | 400  | A resource is bound as a consuming input by more than one downstream call.                                                                  |
| `resolve_error`              | 500  | Server-side error resolving the flow against the manifest. Retry is usually safe.                                                           |
| `preparation_error`          | 422  | An amount that required on-chain resolution (for example, a vault share-price) could not be determined — the read returned `0` or reverted. |
| `no_route_error`             | 404  | The routing layer could not find a path for a requested `lifi.zap` `resourceOut` target on the requested chain.                             |
| `lowering_error`             | 500  | Server-side error lowering a high-level op into VM bytecode. Retry is usually safe.                                                         |
| `simulation_error`           | 500  | Transport or infrastructure failure during simulation. Retry is usually safe.                                                               |
| `simulation_setup_error`     | 422  | The simulator could not set up the simulation (for example, chain RPC unreachable).                                                         |
| `simulation_revert`          | 422  | The simulated transaction reverted on-chain. See **Allow-revert mode** below.                                                               |
| `guard_error`                | 422  | A guard assertion would fail at execution time given the simulated values. Loosen tolerance or investigate the quote.                       |
| `compilation_error`          | 500  | Server-side error producing the final calldata. Retry is usually safe.                                                                      |
| `verification_error`         | 500  | The compiled artifact failed the service's policy verification (contract allowlist, transfer pattern, instruction limit).                   |
| `price_impact_exceeded`      | 422  | The aggregate USD price impact exceeded the bound passed in `run.maxPriceImpactBps`. Lower expectations or accept higher impact.            |
| `provider_error`             | 422  | An upstream provider (quote or routing) returned an error while resolving the flow.                                                         |
| `subgraph_simulation_revert` | 422  | A segment of the simulated flow reverted on-chain.                                                                                          |
| `continuation_error`         | 400  | A multi-step continuation request could not be resumed (for example, the referenced prior step is missing or invalid).                      |
| `fee_resolution_error`       | 422  | The integrator fee for the flow could not be resolved.                                                                                      |
| `fee_resolution_unavailable` | 503  | Fee resolution is temporarily unavailable. Retry with backoff.                                                                              |
| `flashloan_unauthorized`     | 422  | A flashloan step was requested but is not authorized for this integration.                                                                  |

## Recovery hints

* **400-class kinds** indicate a problem the *caller* must fix: the Flow JSON, the ref grammar, or the input bindings. Re-submitting the same request will fail the same way.
* **404 (`no_route_error`)** means the routing graph has no edge matching the requested input/output pair on the requested chain. Check [Supported Protocols & Chains](/composer/protocols-and-chains) for current coverage; the targeted vault may not yet be a routing edge.
* **422-class kinds** are *runtime / data* problems. Adjust tolerances (`slippage`, `maxPriceImpactBps`), wait for on-chain state to settle, or surface the error to your user.
* **500-class kinds** are server-side. Retry with backoff; if the error persists, contact LI.FI.

## Allow-revert mode

When `run.simulationPolicy` is `"allow-revert"`, a `simulation_revert` no longer fails the call. Instead, the response returns the compiled `transactionRequest` *together with* the revert diagnostics on the partial result's `simulationRevert` field (HTTP 206). Use this when you want to surface the revert reason to the user rather than hide it.

See [Guards](/composer/composer-api/concepts/simulation-and-guards) for how `guard_error` is produced and [Execution Model](/composer/composer-api/concepts/execution-model) for where each error kind originates in the compile pipeline.

## See also

* [Execution Model](/composer/composer-api/concepts/execution-model) — pipeline stages that emit each error kind.
* [Guards](/composer/composer-api/concepts/simulation-and-guards) — observation-to-assertion mechanism behind `guard_error`.
* [Flow wire format](/composer/composer-api/reference/flow-wire-format) — the request and response shape returned by `POST /compose`.