Skip to main content
A failed Composer request returns { "success": false, "error": … }. An allow-revert partial result (HTTP 206) also carries data; see Allow-revert mode. For success bodies, see Flow Schema: 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.

Compose error body

Match on kind, path and port. Treat message and fix as text for people: they can change in any release.
string
required
The error kind. One of the error kinds or route error kinds.
string
required
Human-readable description. Not stable; do not parse it.
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).
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.
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_errors. Server faults never carry path, port or fix.
{ 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.
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.
string[]
preparation_error only. The node ids of the prepared ops that succeeded.
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.
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.

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.

Route error kinds

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

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 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:
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:
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; 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.
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