> ## Documentation Index
> Fetch the complete documentation index at: https://docs.paysight.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Error codes

> Structured ERROR event codes from payment submission

When validation fails or a submit guard blocks payment, the widget emits an `ERROR` event **before** or **instead of** `PAYMENT_ERROR`.

```typescript theme={null}
{
  type: 'ERROR';
  payload: {
    code: PaymentErrorCode;
    message: string;
    missingFields?: string[];  // present for VALIDATION_FAILED
  };
}
```

## Payment submission codes

| Code                    | When                                                               | What to do                                                      |
| ----------------------- | ------------------------------------------------------------------ | --------------------------------------------------------------- |
| `VALIDATION_FAILED`     | Missing or invalid card/fields                                     | Show `message`; check `missingFields`                           |
| `PAYMENT_IN_PROGRESS`   | Submit already running or payment completed                        | Disable pay button; wait or reset session                       |
| `INVALID_MODE`          | Wrong method for current mode (e.g. `submitPayment` during upsell) | Call `submitUpsell()` instead                                   |
| `NOT_READY`             | Widget still loading                                               | Wait for `READY`                                                |
| `NO_CARD_FORM`          | Card form hidden (wallet-only layout)                              | Use wallet or wait for fallback UI                              |
| `DUPLICATE_TRANSACTION` | Upsell already charged for this `initialPaymentSession`            | Treat as success; redirect (also emitted as its own event type) |

## Examples

### Validation failed

```javascript theme={null}
// payload:
{
  code: 'VALIDATION_FAILED',
  message: 'Please complete all required fields',
  missingFields: ['email', 'cardNumber']
}
```

### Wrong submit method

```javascript theme={null}
{
  code: 'INVALID_MODE',
  message: 'submitPayment is not available in upsell mode'
}
```

### Missing upsell session

When `usePreviousPaymentMethod: true` without `upsell.initialPaymentSession`:

```javascript theme={null}
{
  code: 'VALIDATION_FAILED',
  message: 'Initial session missing'
}
```

## SDK initialization errors

Config and messaging errors use separate SDK `ERROR_CODES` (e.g. `INVALID_CONFIG`, `COMMUNICATION_ERROR`) and are passed to `onError` — not the `ERROR` event type above.

## Related

* [Events reference](/widget-sdk/reference/events)
* [External payment button](/widget-sdk/guides/external-payment-button)
* [Error handling example](/widget-sdk/examples/error-handling)