{ "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
kindand comes from the compose routes, such asPOST /composeandPOST /compose/route. - A middleware error carries a
typeand comes from authentication, rate limiting and request-schema checks on any route. See Middleware errors.
Compose error body
kind, path and port. Treat message and fix as text for people: they can change in any release.
The error kind. One of the error kinds or route error kinds.
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).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.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.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.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.Kind-specific diagnostics:
simulation_revert:{ code, rawErrorBytes, decodeResult?: { errorCandidates?: [{ decodedErrorSignature, decodedParams[] }], error? } }.no_route_errorfromPOST /compose/route:{ maxHops, searchTruncated }.searchTruncated: truemeans 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
TheComposeErrorKind 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
TheComposeRouteErrorKind union. Compose routes raise these outside the compile pipeline, in the same envelope.
Continuation errors
Acontinuation.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), orquote_failed(the second quote, to the escrow, failed).cause: onquote_failed, the kind of the failed quote, such asno_route_errororprovider_error.quoted:{ min, expected, etaSeconds? }of the quote that failed, or of the first quote forquote_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.
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 usestype, 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
runfields. Re-submitting the same request fails the same way. Readpath,portandfix. - 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. Forpreparation_error, drop or fix the nodes infailedOpsand resubmit. delivery_error: recompile. Never fund the escrow indetails.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
retryAfterseconds.
Allow-revert mode
Withrun.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.
See also
- Simulation and guards: how a guard fails with
guard_error. - Cross-chain flows: the rules behind continuation errors.
- SDK reference:
ComposeErrorand its type guards.

