Error Handling

Handle validation before you call state-changing methods. Handle SDK errors at the boundary where your app can show a user-facing message or retry.

LTV Validation

const ltv = client.quote.calculateLtv(request, pools, prices);

if (ltv.validationErrors.length > 0) {
  return {
    ok: false,
    message: ltv.validationErrors.map((error) => error.message).join(" "),
  };
}

SDK Errors

import {
  LiquidiumError,
  LiquidiumErrorCode,
  SimpleLoanCreatedError,
} from "@liquidium/client";

try {
  const loan = await client.simpleLoans.create(request);
  return loan;
} catch (error) {
  if (error instanceof SimpleLoanCreatedError) {
    return client.simpleLoans.get({ loanId: error.loanId });
  }

  if (error instanceof LiquidiumError) {
    if (error.code === LiquidiumErrorCode.REQUEST_TIMEOUT) {
      // Show retry copy or use the app's retry path.
    }

    throw new Error(error.message);
  }

  throw error;
}

Use the exported LiquidiumErrorCode values when your UI needs different copy for timeout, transport, validation, or protocol failures.

SimpleLoanCreatedError means the remote loan was created but response hydration failed. Recover with the error's loanId or ref through client.simpleLoans.get(...). Do not call create(...) again because that can create a duplicate loan.

Borrow and withdraw amounts below SDK minimums throw or return validation errors before state-changing calls. Use getMinimumBorrowAmount(asset) and getMinimumWithdrawAmount(asset) to show the minimum next to amount inputs.

Destination Validation

Lending outflow and Simple Loan destinations are validated against the selected asset and delivery chain:

Asset path	Chain	Accepted destination family
BTC L1	"BTC"	Bitcoin mainnet chain address
ETH L1 USDC/USDT	"ETH"	EVM chain address
ICP native	"ICP"	IC principal, ICRC account, or ICP account identifier
ckBTC, ckUSDC, ckUSDT	"ICP"	IC principal

Lending uses chain and receiver. Simple Loans use borrow.chain, borrow.destination, refund.chain, and refund.destination. Prefer typed destination objects when the account family matters.

Malformed addresses throw LiquidiumError with LiquidiumErrorCode.INVALID_ADDRESS. Asset, chain, or destination-family mismatches throw LiquidiumErrorCode.VALIDATION_ERROR. Catch both at the form boundary before retrying the flow.