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
See Error codes for the full code union.
Example
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:
Reuse a single renderer for both surfaces. See 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() or an internal getter) 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 Plaid 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.
See also
Last modified on July 28, 2026
