> ## Documentation Index
> Fetch the complete documentation index at: https://docs.layerswap.io/llms.txt
> Use this file to discover all available pages before exploring further.

# onError

> Triggered when a runtime error occurs inside the widget.

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.

<Note>
  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](/widget/delivery-and-security#two-error-channels).
</Note>

```tsx theme={null}
<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:

```TypeScript theme={"system"} theme={null}
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:

```tsx theme={null}
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);
    }
  },
};
```