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

# Error handling

> Catch EscrowCheckoutError and branch on its code.

All failures thrown by the SDK are instances of `EscrowCheckoutError`, which
extends the native `Error` with a machine-readable `code`.

```ts theme={null}
class EscrowCheckoutError extends Error {
  code: EscrowCheckoutErrorCode;
  status?: number;   // HTTP status, when the error came from a network call
  details?: unknown; // extra context, when available
}
```

## Handling errors

```ts theme={null}
import { pay, EscrowCheckoutError } from 'payluk-escrow-inline-checkout';

try {
  await pay({
    paymentToken: 'PY_8AB12C9D3045',
    reference: 'order_2026_0001',
    redirectUrl: 'https://yourapp.com/checkout/complete',
  });
} catch (err) {
  if (err instanceof EscrowCheckoutError) {
    switch (err.code) {
      case 'NOT_INITIALIZED':
        // call initEscrowCheckout() first
        break;
      case 'INVALID_INPUT':
        // fix the pay() arguments
        break;
      default:
        console.error(err.code, err.status, err.details);
    }
  }
}
```

When using the React hook, the same error is surfaced on the hook's `error`
field instead of being thrown, so no `try/catch` is needed.

## Error codes

| Code               | Meaning                                                |
| ------------------ | ------------------------------------------------------ |
| `NOT_INITIALIZED`  | `pay()` was called before `initEscrowCheckout()`.      |
| `BROWSER_ONLY`     | Called outside a browser (e.g. during SSR).            |
| `INVALID_INPUT`    | A required `pay()` argument is missing or malformed.   |
| `WIDGET_LOAD`      | The widget script failed to load.                      |
| `NETWORK`          | A network request failed.                              |
| `SESSION_CREATE`   | The checkout session could not be created.             |
| `SESSION_RESPONSE` | The session-create response was missing or unexpected. |

<Tip>
  `NOT_INITIALIZED`, `BROWSER_ONLY` and `INVALID_INPUT` are developer/integration
  errors; fix them in code. `WIDGET_LOAD`, `NETWORK`, `SESSION_CREATE` and
  `SESSION_RESPONSE` are runtime conditions worth retrying or reporting to the
  buyer.
</Tip>