Error codes

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`

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 fires. onError does not.

Get started

Elements

Options

Events

Theming

Guides

Codes

Switching on `code`

Wallet availability is not an error

Shopper abandonment is not an error

See also

​Codes

​Switching on code

​Wallet availability is not an error

​Shopper abandonment is not an error

​See also

Codes

Switching on `code`

Wallet availability is not an error

Shopper abandonment is not an error

See also