Layerswap Docs

The callbacks.onError event fires when the widget encounters an error at runtime — a failed API call, a failed transaction, a wallet error, and so on.

This callback reports errors inside a loaded, running widget. Failures to load the widget itself (network, manifest, signature issues) surface through the top-level onError prop instead — see Widget delivery and security.

<LayerswapWidget
  config={widgetConfig}
  callbacks={{
    onError: (error) => {
      console.error("Widget error:", error)
    },
  }}
/>

Callback Argument Value

The payload is a discriminated union — switch on error.type to handle specific categories. Every variant carries the base error fields:

type BaseErrorProps = {
  name?: string;
  message: string;
  stack?: string;
  cause?: unknown;
}

The type values and their extra fields:

`type`	Meaning	Extra fields
`APIError`	A Layerswap API request failed	`endpoint`, `status`, `statusText`, `responseData`, `requestUrl`, `requestMethod`
`SwapFailed`	The swap failed	—
`ErrorFallback`	The widget UI crashed into its error fallback	—
`NotFound`	A requested resource wasn’t found	—
`SwapWithdrawalError` / `TransactionFailed` / `SwapCatchupError`	A wallet withdrawal / transaction failed	`swapId`, `transactionHash`, `fromAddress`, `toAddress`
`GasMiscalculation`	Requested amount + gas exceeds wallet balance	`requestedAmount`, `walletBalance`, `calculatedGas`, `difference`, `network`, `token`
`TransactionNotDetected`	A sent transaction wasn’t detected on-chain in time	—
`ChainError`	Chain-level error (e.g. switching networks)	—
`TransferError`	Transfer execution error	—
`WalletError`	Wallet connection / interaction error	—
`BalanceResolverError` / `BalanceProviderError`	Balance fetching failed	`network`, `address`, `request_url`, `response_status`, …
`MaxPriorityFeePerGasError` / `FeesPerGasError` / `GasPriceError` / `GasProviderError`	Gas estimation failed	—
`AlertUI`	An alert was shown to the user inside the widget	—

Example of handling some categories:

const callbacks = {
  onError: (error) => {
    switch (error.type) {
      case 'APIError':
        reportApiIssue(error.endpoint, error.status);
        break;
      case 'TransactionFailed':
        trackFailedTransaction(error.swapId, error.transactionHash);
        break;
      default:
        console.warn('Widget error:', error.type, error.message);
    }
  },
};

Start here

Configuration

Production

Guides & tools

Self-bundled Widget

onError

Callback Argument Value

​Callback Argument Value

Callback Argument Value