Field errors

Validation failures always surface as a FieldError[], both in-flight on onChange.errors and at submit time on onError.fieldErrors. Reuse one renderer across both surfaces.

Shape

interface FieldError {
  field: string;   // element-specific key
  code: string;    // stable, machine-readable
  message: string; // already localized, safe to render to the shopper
  source?: string; // Checkout-only, role-based grouping
}

`field`

Identifies which input inside the element failed. Bucket errors by field to render them next to the matching input.

Element	`field` values
`email`	`'email'`
`fullName`	`'fullName'` (single mode), or `'firstName'` / `'lastName'` (split mode)
`phone`	`'phone'`
`companyName`	`'companyName'`
`billingAddress`, `shippingAddress`	`'line1'`, `'line2'`, `'city'`, `'state'`, `'zip'`, `'country'`; plus `'fullName'` / `'firstName'` / `'lastName'` when the `fullName` slot is configured
`card`	`'cardNumber'`, `'expiryDate'`, `'cvc'`, `'holderName'`, `'postalCode'`
`bank`	`'routingNumber'`, `'accountNumber'`, `'confirmAccountNumber'`, `'accountType'`, or the synthetic `'bank'` at submit time in address-lookup mode when the shopper has not linked
Custom elements	The element’s configured `name`

`code`

Common codes:

Code	Meaning
`'required'`	Empty input on a required field.
`'invalid_format'`	Format check failed (for example, phone E.164, ZIP shape).
`'invalid'`	Card secured fields (the specific format is opaque to the SDK).
`'custom'`	The `validate` callback returned a message.
`'min'` / `'max'`	Numeric range violation on `number` custom elements.
`'mismatch'`	Bank confirm-account-number does not match the primary account number.
Zod issue codes	For built-in schema failures: `'too_small'`, `'too_big'`, `'invalid_string'`, and so on.

code is not part of a closed union; new codes may be added. Prefer rendering message and switching on code only when you have a specific behavior tied to a specific failure.

`message`

Already localized and shopper-safe. Render it as-is next to the input, in an inline error slot, or in a summary.

`source` (Checkout only)

Every Checkout-emitted FieldError carries a source string identifying which slot of the value envelope the field belongs to:

'contact' for email, full name, phone, and company name.
'billingAddress' for the billing-address atoms.
'shippingAddress' for the shipping-address atoms (when the slot is configured).
'paymentMethod' for card, bank, and wallet fields.
'customElement' for any configured custom-element slot.

source maps 1:1 to top-level keys on CheckoutElementValue. Bucket errors by source to render them in the right section of your form.

checkout.on('onChange', ({ errors }) => {
  const contactErrors = (errors ?? []).filter(e => e.source === 'contact');
  paintContactErrors(contactErrors);
});

Standalone elements never set source; use field directly.

Example renderer

function paintFieldErrors(errors) {
  document.querySelectorAll('[data-field-error]').forEach(el => (el.textContent = ''));
  for (const err of errors ?? []) {
    const el = document.querySelector(`[data-field-error="${err.field}"]`);
    if (el) el.textContent = err.message;
  }
}

Get started

Elements

Options

Events

Theming

Guides

Shape

`field`

`code`

`message`

`source` (Checkout only)

Example renderer

See also

​Shape

​field

​code

​message

​source (Checkout only)

​Example renderer

​See also

Shape

`field`

`code`

`message`

`source` (Checkout only)

Example renderer

See also