Errors

A failed POST /compose returns a structured ComposeError:

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:

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 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 for how guard_error is produced and Execution Model for where each error kind originates in the compile pipeline.

Introduction

Integrate via Composer API

Integrate via LI.FI API

Resources

Error kinds

Recovery hints

Allow-revert mode

See also

​Error kinds

​Recovery hints

​Allow-revert mode

​See also

Error kinds

Recovery hints

Allow-revert mode

See also