Skip to main content
Handle errors from the Billing SDK using structured error classes. Each error type provides specific information to help you debug issues and display appropriate messages to your users.

​
Error classes

The SDK includes the following error types:
  • ValidationError - Invalid input or configuration (e.g., missing required fields, invalid field values)
  • APIError - API-level errors from the Funnelfox backend (e.g., invalid price, double purchase, payment failures)
  • PrimerError - Errors originating from the Primer SDK during payment processing
  • CheckoutError - Errors during the checkout lifecycle (e.g., initialization or state management issues)
  • NetworkError - Network connectivity or request failures

​
Handle errors

You can catch and handle each error type to provide appropriate user feedback: 
import {
  ValidationError,
  APIError,
  PrimerError,
  CheckoutError,
  NetworkError,
} from '@funnelfox/billing';

try {
  const checkout = await createCheckout(config);
} catch (error) {
  if (error instanceof ValidationError) {
    // Invalid input
    console.log('Field:', error.field);
    console.log('Value:', error.value);
    console.log('Message:', error.message);
  } else if (error instanceof APIError) {
    // API error
    console.log('Status:', error.statusCode);
    console.log('Error Code:', error.errorCode); // e.g., 'double_purchase'
    console.log('Error Type:', error.errorType); // e.g., 'api_exception'
    console.log('Request ID:', error.requestId); // For support
    console.log('Message:', error.message);
  } else if (error instanceof PrimerError) {
    // Primer SDK error
    console.log('Primer error:', error.message);
    console.log('Original:', error.primerError);
  } else if (error instanceof CheckoutError) {
    // Checkout lifecycle error
    console.log('Phase:', error.phase);
    console.log('Message:', error.message);
  } else if (error instanceof NetworkError) {
    // Network/connectivity error
    console.log('Network error:', error.message);
    console.log('Original:', error.originalError);
  }
}

​
Common error codes

  • double_purchase - User already has an active subscription
  • invalid_price - Price ID not found
  • invalid_customer - Customer data validation failed
  • payment_failed - Payment processing failed