Skip to content

Error handling

Error classes, decline codes, and handling strategies for the FunnelFox Payments Web SDK

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.

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.

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

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);
}
}

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.

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

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.

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.

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