> ## 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, error body fields, and recovery hints.

A failed Composer request returns `{ "success": false, "error": … }`. An allow-revert partial result (HTTP 206) also carries `data`; see [Allow-revert mode](#allow-revert-mode). For success bodies, see [Flow Schema: 200 response](https://docs.li.fi/composer/composer-api/reference/flow-wire-format.md#200-response).

`error` has one of two shapes:

* A **compose error** carries a `kind` and comes from the compose routes, such as `POST /compose` and `POST /compose/route`.
* A **middleware error** carries a `type` and comes from authentication, rate limiting and request-schema checks on any route. See [Middleware errors](#middleware-errors).

## Compose error body

```json theme={"system"}
{
  "success": false,
  "error": {
    "kind": "validation_error",
    "message": "continuation.settle validity.expiresAtMs 1793000000000 is not in the future (current time 1793003600000); an already-expired continuation must not register an escrow",
    "path": "settle",
    "fix": "set config.validity.expiresAtMs to a time in the future"
  }
}
```

Match on `kind`, `path` and `port`. Treat `message` and `fix` as text for people: they can change in any release.

**kind** `string` *required*

The error kind. One of the [error kinds](#error-kinds) or [route error kinds](#route-error-kinds).

**message** `string` *required*

Human-readable description. Not stable; do not parse it.

**path** `string`

Where the error points: a node id for a rejection of an authored node (for example `settle`), or a request path for a rejection of the request shape (for example `run.sweepTo`).

**port** `string`

The input port of the node at `path` whose binding caused the error. Present when the rejection is about what a port binds, not about the node's config.

**fix** `string`

The one edit that clears the error, written for the flow author. Always present on `continuation.settle` authoring rejections; may be absent on other `validation_error`s. Server faults never carry `path`, `port` or `fix`.

**shortfall** `\{ required: string; available: string \}`

Present when the cause is an amount that cannot cover what a step needs. `required` is the least amount that clears the step, `available` is what the flow had. Both are decimal strings in the token's smallest unit.

**failedOps** `FailedPreparedOp[]`

`preparation_error` only. One entry per prepared op that failed: `{ callId, op, kind, message, path?, port?, fix?, shortfall? }`. `callId` is the failing node's id; each entry has its own `kind`.

**succeededOps** `string[]`

`preparation_error` only. The node ids of the prepared ops that succeeded.

**details** `object`

Kind-specific diagnostics:

* `simulation_revert`: `{ code, rawErrorBytes, decodeResult?: { errorCandidates?: [{ decodedErrorSignature, decodedParams[] }], error? } }`.
* `no_route_error` from `POST /compose/route`: `{ maxHops, searchTruncated }`. `searchTruncated: true` means the planner hit its work bound and may have missed a longer route.
* `delivery_error`: `{ reason, cause?, quoted, escrow? }`. See [Delivery errors](#delivery-errors).

`sdk_outdated` and `server_outdated` errors also carry `sdkVersion` and `serverVersion`; `sdk_outdated` adds `minimumSdkVersion`.

### In the SDK

`@lifi/composer-sdk` throws every non-2xx response as a `ComposeError` with the same fields, plus an SDK-level `code` and the HTTP `status`. It resolves a 206 as `status: 'partial'` instead of throwing, and exposes a `delivery_error`'s `details` as `err.delivery`. For the type guards, see [SDK reference: errors](https://docs.li.fi/composer/composer-api/reference/sdk-api.md#errors).

## Error kinds

The `ComposeErrorKind` union in `@lifi/compose-spec` 0.14.0. The SDK `code` column is the `code` the SDK sets for the HTTP status.

| Kind | HTTP | SDK `code` | When |
| - | - | - | - |
| `decode_error` | 400 | `VALIDATION_ERROR` | The Flow JSON fails the wire schema below its top level: a missing node or input field, a wrong type, a malformed address, an unknown key, or a node id that is empty or `__proto__` (including inside a `continuationFlow`). A missing top-level field (`version`, `id`, `chainId`, `inputs`, `nodes`) fails the request schema first and gets the middleware `VALIDATION_ERROR`. |
| `validation_error` | 400 | `VALIDATION_ERROR` | The Flow is well-formed but wrong: an unknown op or guard, a bad or unresolved `$ref`, a missing or extra bind, a type mismatch, a reserved or duplicate node id, a config the op rejects, both `run.sweepTo` and `flow.epilogue` set, or a `continuation.settle` authoring rule broken (see [Continuation errors](#continuation-errors)). |
| `linearity_error` | 400 | `VALIDATION_ERROR` | A resource is consumed more or fewer times than its mode allows, for example bound by two nodes, or a `future` output (such as `lifi.bridge`'s `amountOut`) bound to any input other than a `continuation.settle` `input`. |
| `empty_program` | 400 | `VALIDATION_ERROR` | The Flow compiles to no on-chain effect and has no future output, so there is nothing to submit. |
| `continuation_error` | 400 | `VALIDATION_ERROR` | The settlement service could not re-derive a committed destination flow when it re-submitted it. Your own compiles never return it; authoring mistakes return `validation_error`. |
| `no_route_error` | 404 | `NOT_FOUND` | No admissible route or quote exists for a requested pair, for example a `lifi.zap` `resourceOut` with no routing edge, or a `POST /compose/route` pair the planner cannot connect. |
| `preparation_error` | 422 | `VALIDATION_ERROR` | Some prepared ops (quotes, on-chain reads) failed and others succeeded. Read `failedOps` and `succeededOps`. |
| `provider_error` | 422 | `VALIDATION_ERROR` | A provider the flow depends on is unusable or returned an unusable answer: the settlement provider is not registered or failed a check, a `fly.swap` quote failed validation, or a delivery quote failed. |
| `resolution_rejected` | 422 | `VALIDATION_ERROR` | A protocol definitively refused the request, for example a failed authorization or eligibility check for a [permissioned vault](https://docs.li.fi/composer/permissioned-products-and-compliance.md). Retrying the same request cannot succeed. |
| `simulation_setup_error` | 422 | `VALIDATION_ERROR` | The simulator could not set up the simulation, for example for a token whose balance it cannot simulate. |
| `simulation_insufficient_funds` | 422 | `VALIDATION_ERROR` | The simulated funding did not cover what the transaction needs. |
| `simulation_gas_limit` | 422 | `VALIDATION_ERROR` | The transaction did not fit the simulation's gas bounds. |
| `simulation_revert` | 422 | `VALIDATION_ERROR` | The simulated transaction reverted under `simulationPolicy: 'strict'`. `details` holds the revert. See [Allow-revert mode](#allow-revert-mode). |
| `subgraph_simulation_revert` | 422 | `VALIDATION_ERROR` | The sub-simulation that resolves intermediate amounts reverted. |
| `guard_error` | 422 | `VALIDATION_ERROR` | A guard cannot hold given the simulated values, or failed. Loosen the tolerance or investigate the quote. |
| `price_impact_exceeded` | 422 | `VALIDATION_ERROR` | The aggregate USD price impact exceeded `run.maxPriceImpactBps`. |
| `flashloan_unauthorized` | 422 | `VALIDATION_ERROR` | No flashloan provider is configured for the chain and kind. Production compiles do not raise it. |
| `delivery_error` | 422 | `VALIDATION_ERROR` | A delivery into a `continuation.settle` escrow no longer fits it. See [Delivery errors](#delivery-errors). |
| `resolve_error` | 500 | `SERVER_ERROR` | An op's resolve step failed: context or execution-address resolution, output-family expansion, or amount bounds. |
| `lowering_error` | 500 | `SERVER_ERROR` | Lowering an op into VM bytecode failed. |
| `simulation_error` | 500 | `SERVER_ERROR` | Internal simulation failure. |
| `compilation_error` | 500 | `SERVER_ERROR` | Compiler or tooling failure, including failures of the continuation tooling. |
| `verification_error` | 500 | `SERVER_ERROR` | The request to the service that verifies the compiled program failed. Verification findings never fail the compile, and no call target is rejected. Retry, then contact LI.FI support. |
| `simulation_rpc_error` | 502 | `SERVER_ERROR` | The simulator's RPC node failed. Retryable. |
| `resolution_error` | 503 | `SERVER_ERROR` | Data the flow needs from a protocol or service could not be fetched (a transient upstream fault), for example a deposit authorization or the settlement service during escrow registration. Retry with backoff. |
| `deadline_exceeded` | 503 | `SERVER_ERROR` | The request hit the server's wall-clock budget and was cancelled. Retry with backoff. |

## Route error kinds

The `ComposeRouteErrorKind` union. Compose routes raise these outside the compile pipeline, in the same envelope.

| Kind | HTTP | SDK `code` | When |
| - | - | - | - |
| `chain_validation_error` | 400 | `VALIDATION_ERROR` | The chain is not supported. `GET /chains` lists the supported ones. |
| `sdk_outdated` | 400 | `VALIDATION_ERROR` | The `x-lifi-composer-sdk` request header names an SDK older than the server serves (the floor is 0.5.0). Upgrade `@lifi/composer-sdk` and `@lifi/compose-spec`. |
| `server_outdated` | 400 | `VALIDATION_ERROR` | The SDK is newer than the server. Pin both packages to the server's version (the `x-lifi-composer-version` response header) or wait for the rollout. The SDK also raises this itself when that header is older than its own version. |
| `unsupported_token` | 422 | `VALIDATION_ERROR` | A token is not supported. |
| `zero_output` | 422 | `VALIDATION_ERROR` | The compiled flow delivers zero of a terminal output. |
| `manifest_error` | 500 | `SERVER_ERROR` | The manifest could not be built. |
| `service_unavailable` | 503 | `SERVER_ERROR` | The compose pipeline is not initialised yet. Retry with backoff. |
| `verification_unavailable` | 503 | `SERVER_ERROR` | The execution address could not be verified. Retry with backoff. |
| `deployment_check_unavailable` | 503 | `SERVER_ERROR` | The service could not determine whether your execution proxy is deployed. Retry with backoff. |

## Continuation errors

A `continuation.settle` node that breaks an authoring rule fails with a 400 `validation_error`, not with `continuation_error`. `path` is the settle node (or the node at fault), `port` is set when the problem is a binding, and `fix` names the edit. When the compiler cannot derive a verifiable settlement from the destination flow, the message reads `continuation verification derivation failed (<reason>): …`.

The [`continuation.settle` errors](https://docs.li.fi/composer/composer-api/ops/continuation-settle#errors) table owns every settle-node error: each `validation_error` case, each derivation `<reason>`, `delivery_error`, `price_impact_exceeded`, `provider_error` and `resolution_error`, with its cause and fix.

### Delivery errors

`delivery_error` (422) means a `lifi.bridge` or `lifiIntents.order` delivering into a settle node's escrow no longer fits that escrow. `path` is the producer node. `details` carries:

* `reason`: `floor_drift` (the second quote's minimum fell below the escrow's registered minimum funding), `eta_exceeds_expiry` (the escrow expires before the delivery's ETA allows), or `quote_failed` (the second quote, to the escrow, failed).
* `cause`: on `quote_failed`, the kind of the failed quote, such as `no_route_error` or `provider_error`.
* `quoted`: `{ min, expected, etaSeconds? }` of the quote that failed, or of the first quote for `quote_failed`.
* `escrow`: `{ chainId, address, floor, expiresAtMs }` of the escrow this compile registered and abandoned. Present only when the failure came after registration. Never fund it; it expires unfunded.

A `quote_failed` caused by an amount the quote could not cover also carries `shortfall` at the top level. Recompile: each compile quotes and registers a fresh escrow.

## Middleware errors

Authentication, rate limiting, load shedding and request-schema validation run before the compose handler, on every route. Their body uses `type`, not `kind`:

```json theme={"system"}
{ "success": false, "error": { "type": "UNAUTHORIZED", "message": "API key is required" } }
```

| `type` | HTTP | When |
| - | - | - |
| `UNAUTHORIZED` | 401 | The `x-lifi-api-key` header is missing or invalid. Get a key at [portal.li.fi](https://portal.li.fi). |
| `RATE_LIMITED` | 429 | Too many requests. Wait `retryAfter` seconds. |
| `SERVICE_UNAVAILABLE` | 503 | The service is shedding load. Wait `retryAfter` seconds. |
| `VALIDATION_ERROR` | 400 | The request body fails the route schema, for example a missing top-level Flow field, an unknown key in `run` (such as the removed `integratorFeeBps`) or a malformed `signer`. |
| `SERVER_ERROR` | 500 | Unhandled server error. |

A middleware `VALIDATION_ERROR` lists each failure in `issues`. `path` is a JSON pointer into the request body; for an unknown key it points at the object that holds the key. For example, an unknown key in `run`:

```json theme={"system"}
{
  "success": false,
  "error": {
    "type": "VALIDATION_ERROR",
    "message": "Invalid request format",
    "issues": [{ "path": "/run", "message": "Unrecognized key: \"integratorFeeBps\"" }]
  }
}
```

`RATE_LIMITED` and `SERVICE_UNAVAILABLE` bodies may also carry `retryAfter` (seconds). The SDK maps 401 to `code: 'UNAUTHENTICATED'`, 429 to `RATE_LIMITED` and 5xx to `SERVER_ERROR`; `kind` is then undefined.

## Recovery hints

* **400 kinds** are problems the caller must fix: the Flow JSON, the ref grammar, the bindings or the `run` fields. Re-submitting the same request fails the same way. Read `path`, `port` and `fix`.
* **404 (`no_route_error`)** means the routing graph has no edge for the requested pair on that chain. Check [Supported Protocols & Chains](https://docs.li.fi/composer/protocols-and-chains.md); the target vault may not be a routing edge yet.
* **422 kinds** are runtime or data problems. Adjust tolerances (`slippage`, `maxPriceImpactBps`), fund the inputs, wait for on-chain state to settle, or surface the error to your user. For `preparation_error`, drop or fix the nodes in `failedOps` and resubmit.
* **`delivery_error`**: recompile. Never fund the escrow in `details.escrow`.
* **500 kinds** are server-side. Retry with backoff; if the error persists, contact LI.FI.
* **502 (`simulation_rpc_error`) and 503 (`resolution_error`, `deadline_exceeded`, `service_unavailable`, `verification_unavailable`, `deployment_check_unavailable`)** are transient. Retry with exponential backoff.
* **401 and 429**: set a valid API key; on 429, wait `retryAfter` seconds.

## Allow-revert mode

With `run.simulationPolicy: "allow-revert"`, a simulation revert returns HTTP 206 with the compiled transaction and the revert diagnostics in `data.simulationRevert`, instead of failing with `simulation_revert`. The same applies when the `run.simulateUserProgram` simulation reverts. For the fields of `data`, see [Flow Schema: 206 response](https://docs.li.fi/composer/composer-api/reference/flow-wire-format.md#206-response).

> [!WARNING]
>
> Never fund an escrow from a 206 result, even though it can carry a registered escrow and a `fundEscrow` action. Fix the revert and recompile.

## See also

* [Simulation and guards](https://docs.li.fi/composer/composer-api/concepts/simulation-and-guards.md): how a guard fails with `guard_error`.
* [Cross-chain flows](https://docs.li.fi/composer/composer-api/concepts/cross-chain-flows.md): the rules behind continuation errors.
* [SDK reference](https://docs.li.fi/composer/composer-api/reference/sdk-api.md#errors): `ComposeError` and its type guards.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.