Error Handling

​

Error Response Format

{
  "detail": "Human-readable error message"
}

​

Common Errors

​

Vault Not Found (404)

{ "detail": "Vault some-vault-id not found" }

​

No Route Found (400)

{ "detail": "No route found for this token/chain combination" }

• Token not supported on the source chain
• Amount too small to bridge
• Liquidity unavailable for this pair

​

Zero Output Amount (400)

{ "detail": "LiFi returned zero output amount" }

​

Contract Calls Quote Unavailable (400)

{ "detail": "LiFi contract calls quote unavailable for this route. Use fallback flow." }

​

No Deposit Router (400)

{ "detail": "No deposit router on chain {chain_id}" }

​

Validation Error (422)

{
  "detail": [
    {
      "loc": ["body", "from_amount"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}

​

Best Practices

1. Always check for approval - It can be null for native token deposits
2. Handle quote expiry - Quotes can become stale. If the build fails, fetch a new quote
3. Poll with backoff - For status checks, start at 15s intervals. Don’t poll faster than every 10 seconds
4. Show the LiFi explorer link - Give users tracking.lifi_explorer so they can independently track their bridge transfer