Skip to main content
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:
KindHTTPWhen
decode_error400Flow JSON is malformed or fails shape validation against the wire schema.
validation_error400Port bindings, ref targets, op or guard names, or other semantic checks fail.
linearity_error400A resource is bound as a consuming input by more than one downstream call.
resolve_error500Server-side error resolving the flow against the manifest. Retry is usually safe.
preparation_error422An amount that required on-chain resolution (for example, a vault share-price) could not be determined — the read returned 0 or reverted.
no_route_error404The routing layer could not find a path for a requested lifi.zap resourceOut target on the requested chain.
lowering_error500Server-side error lowering a high-level op into VM bytecode. Retry is usually safe.
simulation_error500Transport or infrastructure failure during simulation. Retry is usually safe.
simulation_setup_error422The simulator could not set up the simulation (for example, chain RPC unreachable).
simulation_revert422The simulated transaction reverted on-chain. See Allow-revert mode below.
guard_error422A guard assertion would fail at execution time given the simulated values. Loosen tolerance or investigate the quote.
compilation_error500Server-side error producing the final calldata. Retry is usually safe.
verification_error500The compiled artifact failed the service’s policy verification (contract allowlist, transfer pattern, instruction limit).
price_impact_exceeded422The aggregate USD price impact exceeded the bound passed in run.maxPriceImpactBps. Lower expectations or accept higher impact.
provider_error422An upstream provider (quote or routing) returned an error while resolving the flow.
subgraph_simulation_revert422A segment of the simulated flow reverted on-chain.
continuation_error400A multi-step continuation request could not be resumed (for example, the referenced prior step is missing or invalid).
fee_resolution_error422The integrator fee for the flow could not be resolved.
fee_resolution_unavailable503Fee resolution is temporarily unavailable. Retry with backoff.
flashloan_unauthorized422A 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.

​
See also

  • Execution Model — pipeline stages that emit each error kind.
  • Guards — observation-to-assertion mechanism behind guard_error.
  • Flow wire format — the request and response shape returned by POST /compose.