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

# Field errors

> The FieldError shape used on onChange.errors and onError.fieldErrors.

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

```typescript theme={null}
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.

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

Standalone elements never set `source`; use `field` directly.

## Example renderer

```javascript theme={null}
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;
  }
}
```

## See also

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