Error handling

Handle errors from the FunnelFox Payments Web SDK using structured error classes. Each error type provides specific information to help you debug issues and show the right message to your users.

Error classes

Class	When the SDK throws it
`APIError`	FunnelFox Payments returns an error, for example when a session can’t be created or the customer already owns the product.
`NetworkError`	A request fails or times out. The SDK times out a request after 30 seconds and tries it up to three times.
`PrimerError`	Primer fails to load, or a payment method fails to render.
`CheckoutError`	The container isn’t on the page, `updatePrice()` runs during a payment, or the checkout was destroyed.
`ValidationError`	`updatePrice()` gets an empty price point ID.

All of them extend FunnefoxSDKError, which adds code and details to Error. Each error’s name matches its class name.

A missing organization ID throws a plain Error: “orgId is required. Pass it to createCheckout() or call configure() first.” The SDK also exports ConfigurationError, which no method currently throws.

Handle errors

Catch errors from createCheckout() and the other methods to show appropriate feedback.

JavaScript
TypeScript

In JavaScript, check the error class with instanceof:

import {
  ValidationError,
  APIError,
  PrimerError,
  CheckoutError,
  NetworkError,
} from '@funnelfox/billing';

try {
  const checkout = await createCheckout(config);
} catch (error) {
  if (error instanceof APIError) {
    console.log('Status:', error.statusCode);
    console.log('Error code:', error.errorCode); // e.g., 'double_purchase'
    console.log('Request ID:', error.requestId); // For support
  } else if (error instanceof NetworkError) {
    console.log('Network error:', error.message);
  } else if (error instanceof PrimerError) {
    console.log('Primer error:', error.primerError);
  } else if (error instanceof CheckoutError) {
    console.log('Checkout error:', error.message);
  } else if (error instanceof ValidationError) {
    console.log('Invalid field:', error.field, error.value);
  }
}

The type definitions declare the error classes as interfaces, so instanceof doesn’t compile in TypeScript. Narrow by error.name instead:

import type {
  APIError,
  NetworkError,
  PrimerError,
  CheckoutError,
  ValidationError,
} from '@funnelfox/billing';

try {
  const checkout = await createCheckout(config);
} catch (error) {
  if (!(error instanceof Error)) throw error;

  switch (error.name) {
    case 'APIError': {
      const apiError = error as APIError;
      console.log('Status:', apiError.statusCode);
      console.log('Error code:', apiError.errorCode);
      console.log('Request ID:', apiError.requestId);
      break;
    }
    case 'NetworkError':
      console.log('Network error:', (error as NetworkError).originalError);
      break;
    case 'PrimerError':
      console.log('Primer error:', (error as PrimerError).primerError);
      break;
    case 'CheckoutError':
      console.log('Phase:', (error as CheckoutError).phase);
      break;
    case 'ValidationError':
      console.log('Invalid field:', (error as ValidationError).field);
      break;
  }
}

Error properties

Every SDK error has name, message, code, and details. Some classes add more:

APIError: statusCode, errorCode, errorType, requestId, response, declineCode, and declineCodeSource.
NetworkError: originalError, the underlying error.
PrimerError: primerError, the original Primer error.
CheckoutError: phase, the checkout phase that failed.
ValidationError: field and value, the invalid input.

For APIError, code is the error code from FunnelFox Payments when one is present, such as double_purchase when the customer already owns the product. Otherwise, code is one of the ERROR_CODES constants: API_ERROR, NETWORK_ERROR, PRIMER_ERROR, CHECKOUT_ERROR, VALIDATION_ERROR, or SDK_ERROR.

Decline codes

When a payment provider declines a payment, FunnelFox Payments reports a decline code. Use it to tell an insufficient-funds decline apart from other failures, for example to offer a different payment method.

declineCode: The decline code in uppercase, for example "INSUFFICIENT_FUNDS". Empty when the provider reports none.
declineCodeSource: The provider that reported it: "primer", "stripe", or "adyen".

Where you receive them depends on the method:

Method	Where to read the decline code
createCheckout()	The purchase-failure event
Billing.initMethod()	`onPaymentFail`
Billing.stripe.createCardForm()	`onPaymentFail`, or the error `submit()` rejects with
Billing.stripe.purchaseWallet()	`onPaymentFail`, or the error the promise rejects with

onPaymentFail and purchase-failure pass a plain Error with declineCode and declineCodeSource (the PaymentFailure type), not an APIError. Read the fields directly instead of checking the class.

For Stripe card declines during 3DS, the SDK maps Stripe’s error code to the same uppercase format.

await Billing.initMethod(PaymentMethod.PAYMENT_CARD, element, {
  // ...required options
  onPaymentFail: error => {
    if (error.declineCode === 'INSUFFICIENT_FUNDS') {
      showMessage('Your card has insufficient funds. Try another card.');
    } else {
      showMessage(error.message);
    }
  },
});

Learn how FunnelFox Payments uses declines for retries in Decline classification.

Initialization errors

When createCheckout() can’t initialize, the SDK replaces the container’s content with this message:

The payment form didn’t load correctly. Please refresh the page to try again. If the problem persists, please contact support.

The message also shows the request ID when one is available. Style it with the .ff-sdk-error-container class. Share the request ID with support to speed up troubleshooting.

Tax errors

When a tax recalculation fails, the SDK calls onTaxError with an APIError or a NetworkError. Learn more about taxes in the Web SDK.

API reference

Webhook reference

Billing Web SDK

Error classes

Handle errors

Error properties

Decline codes

Initialization errors

Tax errors

​Error classes

​Handle errors

​Error properties

​Decline codes

​Initialization errors

​Tax errors

Error classes

Handle errors

Error properties

Decline codes

Initialization errors

Tax errors