> ## 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.

# Error codes

> The closed union of onError codes and when each fires.

Every `onError` payload carries a `code` from the `OverflowErrorCode` union. The union is closed today but new codes are added in minor releases; always include a `default` branch when switching on it.

## Codes

| Code                  | Fires when                                                                                     | Notes                                                                                                                                                                                                                            |
| --------------------- | ---------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `validation_failed`   | `submit()` was called but inputs are invalid or empty.                                         | `fieldErrors` is always populated. The same per-field failures appear on `onChange.errors` while the shopper is typing.                                                                                                          |
| `not_mounted`         | A method (`submit()`, `validate()`, an internal getter) was invoked before `mount()` resolved. | Programmer error. Guard call sites against early `submit()` calls.                                                                                                                                                               |
| `network`             | A network request to the SDK's backend failed.                                                 | Currently fires from the shared payment-settings fetch on mount. Retriable.                                                                                                                                                      |
| `tokenization_failed` | The card processor rejected a card payload during `submit()`.                                  | Card element only. `cause` carries the raw underlying error.                                                                                                                                                                     |
| `encryption_failed`   | The SDK could not encrypt a sensitive field payload before submission.                         | Card and bank (manual-mode) elements. Usually indicates a stale or missing field-encryption key. For manual-mode bank, call `overflow.invalidateBankFieldEncryptionCache()` and retry. `cause` carries the raw underlying error. |
| `plaid_link_failed`   | The bank-linking modal reported an error or its SDK failed to load.                            | Bank element, address-lookup mode only. Shopper is typically prompted to retry or fall back to manual entry.                                                                                                                     |
| `wallet_failed`       | The wallet sheet errored mid-flow.                                                             | Wallet elements only. Distinct from `available: false` on `onChange`, which is not an error.                                                                                                                                     |
| `unknown`             | The SDK could not classify the underlying failure.                                             | `cause` carries the raw value. Also used for relayed card errors that do not fit the more specific codes.                                                                                                                        |

## Switching on `code`

```javascript theme={null}
element.on('onError', ({ code, message, fieldErrors, cause }) => {
  switch (code) {
    case 'validation_failed':
      paintFieldErrors(fieldErrors);
      break;
    case 'tokenization_failed':
      toast(`Card error: ${message}`);
      logToObservability({ code, cause });
      break;
    case 'plaid_link_failed':
      promptRetryOrManual();
      break;
    case 'wallet_failed':
      toast('Wallet payment failed. Try again or use another method.');
      break;
    case 'network':
      toast('Network error. Try again.');
      break;
    case 'not_mounted':
      // Programmer error. Do not show to shoppers.
      console.error('Guard your submit() call site.');
      break;
    default:
      toast('Something went wrong. Try again.');
      logToObservability({ code, cause });
  }
});
```

## Wallet availability is not an error

A wallet's device-availability probe reporting `available: false` on `onChange` is not an error. `onError` is reserved for actual failures during an active flow. Drive fallback rendering off `onChange`.

## Shopper abandonment is not an error

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

## See also

* [`onError`](/payment-elements/events/on-error)
* [Field errors](/payment-elements/events/field-errors)
* [Handle validation errors](/payment-elements/guides/handle-validation-errors)