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.
Error classes
Section titled “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.
Handle errors
Section titled “Handle errors”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); }}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
Section titled “Error properties”Every SDK error has name, message, code, and details. Some classes
add more:
APIError:statusCode,errorCode,errorType,requestId,response,declineCode, anddeclineCodeSource.NetworkError:originalError, the underlying error.PrimerError:primerError, the original Primer error.CheckoutError:phase, the checkout phase that failed.ValidationError:fieldandvalue, 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
Section titled “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 |
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
Section titled “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
Section titled “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.