SDK Error Reference

interface FanfareError {
  message: string; // Human-readable error message
  code: string; // Machine-readable error code
  status?: number; // HTTP status code (if applicable)
  details?: unknown; // Additional error details
  requestId?: string; // Request ID for support
  correlationId?: string; // Correlation ID for tracking
  retryable: boolean; // Whether the operation can be retried
  retryAfter?: number; // Suggested retry delay in seconds
}

import { FanfareError, ErrorCodes } from "@fanfare-io/fanfare-sdk-core";

try {
  await client.experiences.enter(experienceId);
} catch (error) {
  if (error instanceof FanfareError) {
    switch (error.code) {
      case ErrorCodes.NETWORK_ERROR:
        // Handle network issues
        break;
      case ErrorCodes.RATE_LIMITED:
        // Wait and retry
        await delay(error.retryAfter || 5000);
        break;
      default:
      // Handle other errors
    }
  }
}

if (error.code === ErrorCodes.NETWORK_ERROR) {
  // Show offline indicator
  showOfflineMessage();

  // Retry when connection is restored
  window.addEventListener("online", () => {
    retryOperation();
  });
}

if (error.code === ErrorCodes.TIMEOUT) {
  // Retry with exponential backoff
  const delay = Math.min(1000 * Math.pow(2, attempt), 30000);
  await sleep(delay);
  return retry();
}

if (error.code === ErrorCodes.UNAUTHORIZED) {
  // Clear any stale auth state
  client.auth.logout();

  // Redirect to login or start guest session
  if (requiresAuth) {
    redirectToLogin();
  } else {
    await client.auth.guest();
  }
}

if (error.code === ErrorCodes.SESSION_EXPIRED) {
  // Attempt to refresh the session
  try {
    await client.auth.refresh();
    // Retry the original operation
    return retry();
  } catch {
    // Refresh failed, re-authenticate
    await client.auth.guest();
  }
}

if (error.code === ErrorCodes.INVALID_OTP) {
  // Clear the input and show error
  clearOtpInput();
  showError("Invalid code. Please try again or request a new code.");
}

if (error.code === ErrorCodes.QUEUE_EXPIRED) {
  showMessage("This queue has ended. Join the waitlist for future access.");
  offerWaitlistSignup();
}

if (error.code === ErrorCodes.QUEUE_FULL) {
  showMessage("This queue is currently full.");

  if (waitlistAvailable) {
    offerWaitlistSignup();
  }
}

if (error.code === ErrorCodes.ALREADY_IN_QUEUE) {
  // Get existing position
  const status = client.queues.getStatus(queueId);
  updateUI(status);
}

if (error.code === ErrorCodes.VALIDATION_ERROR) {
  // Display validation errors to user
  const issues = error.details as ValidationIssue[];
  issues.forEach((issue) => {
    showFieldError(issue.path, issue.message);
  });
}

if (error.code === ErrorCodes.RATE_LIMITED) {
  const waitTime = error.retryAfter || 5;
  showMessage(`Please wait ${waitTime} seconds before trying again.`);

  setTimeout(() => {
    enableRetry();
  }, waitTime * 1000);
}

if (error.code === ErrorCodes.INTERNAL_ERROR) {
  // Log for debugging
  console.error("Server error:", error.requestId);

  showMessage("Something went wrong. Please try again.");
  // Automatic retry with backoff
}

if (error.code === ErrorCodes.SERVICE_UNAVAILABLE) {
  showMessage("Service temporarily unavailable. Retrying...");

  // SDK automatically retries
  // Show progress indicator
}

// Ensure client is initialized before use
const client = new FanfareClient({
  publishableKey: "pk_live_...",
});

// Then call methods
await client.experiences.enter(experienceId);

client.on("error", (error: FanfareError) => {
  console.error("Fanfare error:", {
    code: error.code,
    message: error.message,
    requestId: error.requestId,
    retryable: error.retryable,
  });

  // Send to error tracking service
  errorTracker.capture(error, {
    tags: { service: "fanfare", code: error.code },
  });
});

const USER_MESSAGES: Record<string, string> = {
  NETWORK_ERROR: "Connection issue. Please check your internet.",
  RATE_LIMITED: "Too many requests. Please wait a moment.",
  SESSION_EXPIRED: "Your session expired. Please refresh.",
  QUEUE_FULL: "This queue is currently full.",
  // ... more mappings
};

function getUserMessage(error: FanfareError): string {
  return USER_MESSAGES[error.code] || "Something went wrong. Please try again.";
}