Skip to main content
Composer uses the standard LI.FI API error format and codes; see Error Codes for the format and the full list. This page covers what those errors mean for Composer routes and how to handle Composer-specific failures.

API errors (quote and route requests)

Composer is one of many tools the API asks for a route, so the codes are general LI.FI codes. Two need Composer-specific handling:

Tool errors

The 1002 response body carries an errors object that explains why each candidate route was dropped:
  • errors.filteredOut[]: routes that were found but removed, with a reason (for example, price impact above the limit).
  • errors.failed[]: routes where a tool returned no quote. subpaths maps each hop to a list of ToolError entries (type ToolError in @lifi/types), each with errorType, code, tool, message and action.
Composer failures are the entries with tool: "composer". message is free text for logs and can start with an internal prefix in brackets; read code and tool programmatically and do not match on message.

Relevant tool error codes

Example: reading Composer tool errors


Transaction failures

Pre-execution simulation failure

Composer simulates the entire execution path before returning a quote. If simulation fails, the Composer route is dropped and the API returns another route or an error instead of a transaction that would revert. Common causes:
  • The vault is not accepting deposits (paused, full, or restricted)
  • The token path involves incompatible tokens
  • Insufficient liquidity in the swap path

Onchain transaction revert

Simulation runs against chain state at quote time, so a transaction can still revert onchain, for example after front-running or a state change between quote and execution. estimate.toAmountMin and slippage bound the price part of this risk. If a same-chain transaction reverts, the user’s tokens stay in their wallet, but the gas is spent. Retry with a fresh quote.

Cross-chain failure modes

A cross-chain Composer route has two phases: the bridge on the source chain and the Composer deposit on the destination chain. Each phase is atomic within its chain, but the route as a whole is not. If the bridge succeeds and the deposit does not run, the status is DONE with substatus PARTIAL, not FAILED, and the user holds the bridged token on the destination chain. Show receiving.token from the status response and offer a same-chain deposit; see Partial failure handling. For every status and substatus value of GET /v1/status, see Transaction Status Tracking.

Common Composer issues