Error Handling

The SDK provides typed errors for different failure scenarios.

Error Types

FacilitatorError

Base error class. All other errors extend this.

class FacilitatorError extends Error {
  code: string;
  statusCode?: number;
  details?: unknown;
}

VerificationError

Thrown when payment verification fails.

import { VerificationError } from '@openfacilitator/sdk';
 
try {
  await facilitator.verify(payment, requirements);
} catch (error) {
  if (error instanceof VerificationError) {
    console.error('Verification failed:', error.message);
  }
}

SettlementError

Thrown when payment settlement fails.

import { SettlementError } from '@openfacilitator/sdk';
 
try {
  await facilitator.settle(payment, requirements);
} catch (error) {
  if (error instanceof SettlementError) {
    console.error('Settlement failed:', error.message);
  }
}

NetworkError

Thrown when a network request fails (timeout, connection error, etc.).

import { NetworkError } from '@openfacilitator/sdk';
 
try {
  await facilitator.supported();
} catch (error) {
  if (error instanceof NetworkError) {
    console.error('Network error:', error.message);
  }
}

ConfigurationError

Thrown when the SDK is misconfigured.

import { ConfigurationError } from '@openfacilitator/sdk';
 
try {
  new OpenFacilitator({ url: '' }); // Missing URL
} catch (error) {
  if (error instanceof ConfigurationError) {
    console.error('Config error:', error.message);
  }
}

Error Handling Pattern

import {
  OpenFacilitator,
  FacilitatorError,
  VerificationError,
  SettlementError,
  NetworkError
} from '@openfacilitator/sdk';
 
async function processPayment(payment, requirements) {
  try {
    const verification = await facilitator.verify(payment, requirements);
 
    if (!verification.valid) {
      throw new Error(`Invalid payment: ${verification.error}`);
    }
 
    const settlement = await facilitator.settle(payment, requirements);
 
    if (!settlement.success) {
      throw new Error(`Settlement failed: ${settlement.error}`);
    }
 
    return settlement.transactionHash;
 
  } catch (error) {
    if (error instanceof VerificationError) {
      // Handle verification-specific error
    } else if (error instanceof SettlementError) {
      // Handle settlement-specific error
    } else if (error instanceof NetworkError) {
      // Handle network error (retry?)
    } else if (error instanceof FacilitatorError) {
      // Handle other facilitator errors
    } else {
      // Handle unexpected errors
    }
    throw error;
  }
}