Error Handling & Troubleshooting

interface ApiResponseBase {
  success: boolean;        // true if the request succeeded
  message: string;         // human-readable description
  statusCode: number;      // HTTP status code (0 for network errors, 408 for timeout)
  action: string;          // the API endpoint that was called
  isNetworkError: boolean; // true for network failures and timeouts
}

const response = await api.activity.getActivity('some-uuid');

if (!response.success) {
  console.error(`Error: ${response.message}`);
  return;
}

// Safe to use response.activity

const response = await api.cart.createOrUpdateCart(request);

if (!response.success) {
  if (response.isNetworkError) {
    // Connection failed, timeout, or DNS issue
    showMessage('Unable to reach the server. Check your connection and try again.');
  } else if (response.statusCode >= 500) {
    // Server error
    showMessage('Something went wrong on our end. Please try again later.');
  } else {
    // Client error (400, 401, 403, 404, etc.)
    showMessage(response.message);
  }
}

// This returns an error without making a network request
const response = await api.calendar.getActivityCalendar({
  activity: '',  // empty
  month: 13,     // out of range
  year: 2025,
});

// response.success === false
// response.message === 'Activity, month, and year are required'
// response.statusCode === 400
// response.isNetworkError === false

const response = await api.cart.createOrUpdateCart(request);

if (!response.success && response.errorCode !== undefined) {
  switch (response.errorCode) {
    case 4:  // TimeSlotNotAvailable
      showMessage('That time slot is no longer available. Please select another.');
      break;
    case 6:  // EquipmentQuantityExceeded
      showMessage('Not enough equipment available. Please reduce your quantity.');
      break;
    case 9:  // GuestLimitExceeded
      showMessage('Too many guests. Maximum is ' + getGuestLimit());
      break;
    case 19: // CartExpired
      showMessage('Your session has expired. Please start over.');
      resetBooking();
      break;
    default:
      showMessage(response.message);
  }
}

const response = await api.cart.createOrUpdateCart(request);

if (response.success && response.removals?.length) {
  response.removals.forEach(removal => {
    switch (removal.type) {
      case 1: // EquipmentUnavailable
        notify(`Equipment is no longer available and was removed.`);
        break;
      case 2: // EquipmentQuantityReduced
        notify(`Equipment quantity reduced to ${removal.maxQuantity}.`);
        break;
      case 3: // AddonUnavailable
        notify(`An addon was removed because it is no longer available.`);
        break;
      // ... handle other types
    }
  });
}

const response = await api.cart.applyGiftCard({
  giftCardCode: userInput,
  cartId: currentCartId,
});

if (!response.success) {
  switch (response.errorCode) {
    case 1:  // InvalidCode
      showError('That gift card code is not valid.');
      break;
    case 2:  // Expired
      showError('This gift card has expired.');
      break;
    case 3:  // NoBalance
      showError('This gift card has no remaining balance.');
      break;
    case 5:  // AlreadyApplied
      showError('This gift card is already applied to your cart.');
      break;
    case 8:  // LocationMismatch
      showError('This gift card cannot be used at this location.');
      break;
    default:
      showError(response.message);
  }
}

const api = new ResytechApi({ timeout: 15000 }); // 15 seconds

const response = await api.activity.getActivity('uuid');

if (!response.success && response.statusCode === 408) {
  // Request timed out
  showMessage('The request took too long. Please try again.');
}

{
  success: false,
  message: 'Unable to connect to the server',  // or the actual error message
  statusCode: 0,
  action: '/activity/uuid',
  isNetworkError: true
}

async function fetchWithRetry<T>(fn: () => Promise<T & ApiResponseBase>, maxRetries = 3): Promise<T & ApiResponseBase> {
  let lastResponse: T & ApiResponseBase;

  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    lastResponse = await fn();

    if (lastResponse.success) return lastResponse;

    // Only retry network errors
    if (!lastResponse.isNetworkError) return lastResponse;

    // Wait before retrying (exponential backoff)
    if (attempt < maxRetries) {
      await new Promise(r => setTimeout(r, 1000 * attempt));
    }
  }

  return lastResponse!;
}

// Usage
const response = await fetchWithRetry(() => api.activity.getActivity('uuid'));

// Short timeout for health checks
const api = new ResytechApi({ timeout: 5000 });

// Check connectivity
const healthy = await api.health.check();
if (!healthy) {
  showBanner('Service is temporarily unavailable.');
}

const api = new ResytechApi({ debug: true });

api.setDebug(true);   // enable
api.setDebug(false);  // disable

api.blog.setLocationGuid('your-location-guid');

const response = await api.initialization.initialize({ identifier: 'session-id' });
if (response.success) {
  // Token is automatically set on all controllers
}

const response = await api.cart.createOrUpdateCart({ cart: myCart });
if (response.success) {
  sessionStorage.setItem('cartId', response.cartId);
}

// On subsequent requests
const cartId = sessionStorage.getItem('cartId');
await api.cart.applyCoupon({ couponCode: 'SAVE10', cartId });

const response = await api.checkout.checkout(request);

if (response.success && response.clientSecret) {
  // 3D Secure or additional auth required
  const { error, paymentIntent } = await stripe.handleNextAction({
    clientSecret: response.clientSecret,
  });

  if (!error && paymentIntent.status === 'succeeded') {
    // Retry checkout with handledNextAction
    const finalResponse = await api.checkout.checkout({
      ...request,
      handledNextAction: paymentIntent.id,
    });
  }
}

const parsed = JSON.parse(post.content);
console.log(parsed.version); // Should be 2
console.log(Array.isArray(parsed.blocks)); // Should be true