Error handling - Payluk API

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

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

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.

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.