Error Handling Guide

This page provides detailed guide on common error handling throw by the Purse Headless Checkout SDK.

Overview

The Purse Headless Checkout SDK may throw errors during various stages of the checkout process. Custom errors should be thrown using the PurseHeadlessCheckoutError class, which extends the native JavaScript Error class.

Instances of PurseHeadlessCheckoutError will include a message, an error code, a link to the relevant documentation for this error code and optionally an additional payload with more details about the error.

How to handle errors

Purse Headless Checkout SDK errors can be caught like any standard JavaScript error using try...catch blocks.

Example

let checkout: PurseHeadlessCheckout;

try {
  checkout = await Purse.createHeadlessCheckout({
    ...
  });
} catch(e) {
  if (e instanceof PurseHeadlessCheckoutError) {
    switch(e.code) {
      case 'INVALID_INIT_PARAMS':
        // Handle invalid initialization parameters
        break;
      // Handle other error codes as needed
      default:
        console.error('An unexpected error occurred:', e);
    }
  } else {
    console.error('A non-headless checkout error occurred:', e);
  }
}

Common Error Codes

See the dedicated page for a full list of error codes: PurseHeadlessCheckoutErrorCodes.