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

# onError

> Fires when an element rejects an action: validation, network, tokenization, wallet sheet, or bank linking.

`onError` fires when an element cannot complete an action. Every payload carries a stable `code` and a shopper-safe `message`. Validation failures also carry `fieldErrors` for inline rendering.

## Payload

```typescript theme={null}
interface OverflowErrorEvent<T> {
  elementType: T;
  code: OverflowErrorCode;
  message: string;
  fieldErrors?: FieldError[]; // populated when code === 'validation_failed'
  cause?: unknown;            // diagnostics only, not part of the public contract
}
```

See [Error codes](/payment-elements/events/error-codes) for the full `code` union.

## Example

```javascript theme={null}
card.on('onError', ({ code, message, fieldErrors }) => {
  switch (code) {
    case 'validation_failed':
      paintFieldErrors(fieldErrors);
      break;
    case 'tokenization_failed':
      toast(`Card error: ${message}`);
      break;
    case 'network':
      toast('Network error. Try again.');
      break;
    default:
      toast(message);
  }
});
```

## Always handle it

Even elements that mostly drive `onSubmit` (cards, wallets) can fail validation, network, or tokenization. Register an `onError` handler on every element you mount.

## Switch on `code`

The union is closed but new codes are added in minor releases. Keep a `default` branch so new codes surface cleanly.

## Render `message`, not `cause`

* `message` is already localized and shopper-safe. Render it as-is.
* `cause` carries raw underlying exceptions for diagnostics (network stack traces, gateway errors, provider Link errors). Log it to your error tracker; do not surface it to shoppers. Its shape is not part of the public contract.

## Validation errors

For `code: 'validation_failed'`, `fieldErrors` is always populated. The same `FieldError[]` shape appears on `onChange.errors` while the shopper is typing:

```javascript theme={null}
element.on('onError', ({ code, fieldErrors }) => {
  if (code === 'validation_failed') paintFieldErrors(fieldErrors);
});
```

Reuse a single renderer for both surfaces. See [Field errors](/payment-elements/events/field-errors).

Validation failures are not hard failures. Reset the error state on the next `onChange` when the shopper corrects the input.

## Retriable errors

For `network`, `tokenization_failed`, `plaid_link_failed`, and `wallet_failed`, surface a retry affordance. The shopper can attempt the action again once the transient condition clears.

## Programmer errors

`not_mounted` fires when a method (`submit()`, `validate()`, internal getters) is invoked before `mount()` resolves. Treat it as a bug: log loudly in development. In production it usually means the calling code fires `submit()` before the element has mounted; guard the call site.

## Bank

Every bank `onError` envelope additionally carries `bankMode: 'plaid' | 'manual' | null`:

* `'plaid'` for `plaid_link_failed` and address-lookup submit gating.
* `'manual'` for manual-mode atom failures.
* `null` only on `code: 'not_mounted'` (no live element to read the active mode from).

## Wallet "unavailable" is not an error

When a wallet fails its device-availability probe, the element fires `onChange { available: false, reason }` and suppresses `onReady`. `onError` is reserved for actual failures during an active flow (for example, the shopper tapped Pay and the sheet rejected the token). Drive fallback rendering off `onChange`, not `onError`.

## Shopper abandonment is not an error either

When the shopper dismisses a wallet sheet or the bank link modal without authorizing, `onExit` fires. `onError` does not. See [`onExit`](/payment-elements/events/on-exit).

## See also

* [Error codes](/payment-elements/events/error-codes)
* [Field errors](/payment-elements/events/field-errors)
* [Handle validation errors](/payment-elements/guides/handle-validation-errors)