Error Handling

const {data, error} = await storefront.catalog.getProduct("my-product");
if (error?.status === 404) return renderNotFound();
if (error) return renderRetryableError(errorMessage(error, "en"));
return renderProduct(data);

import {
  BehioApiError, BehioNetworkError, toSdkError, type SdkResult,
} from "@behio/storefront-sdk";

async function readCatalogResult<T>(request: Promise<SdkResult<T>>): Promise<SdkResult<T>> {
  try {
    return await request;
  } catch (error) {
    if (error instanceof BehioApiError || error instanceof BehioNetworkError) {
      return {data: null, error: toSdkError(error)};
    }
    throw error;
  }
}

import { errorMessage } from "@behio/storefront-sdk";

const { data, error } = await storefront.cart.addItem({ productId, quantity });
if (error) {
  showToast(errorMessage(error, "cs"));
  // "Produkt Tricko neni v pozadovanem mnozstvi skladem."
}

type BehioErrorCode =
  | "UNAUTHORIZED"          // 401
  | "FORBIDDEN"             // 403
  | "NOT_FOUND"             // 404
  | "VALIDATION_ERROR"      // 400
  | "CONFLICT"              // 409
  | "RATE_LIMITED"          // 429
  | "CART_EMPTY"            // empty cart at checkout
  | "PRODUCT_NOT_FOUND"     // product does not exist
  | "INVALID_CREDENTIALS"   // wrong email/password
  | "INVALID_DISCOUNT"      // discount code invalid
  | "DISCOUNT_EXPIRED"      // discount code expired
  | "TOKEN_EXPIRED"         // auth token expired
  | "TOKEN_INVALID"         // auth token invalid
  | "EMAIL_ALREADY_EXISTS"  // 409 on registration
  | "ORDER_NOT_CANCELLABLE" // order cannot be cancelled
  | "INTERNAL_ERROR"        // 5xx
  | "NETWORK_ERROR"         // network failure
  | "TIMEOUT"               // request timed out
  | "UNKNOWN";              // unrecognized error

const {error} = await storefront.checkout.createOrder(input);
if (error?.status === 400) {
  showFieldErrors(validationFieldMessages(error, "en"));
}

const {error} = await storefront.catalog.getProduct("nonexistent-slug");
if (error?.status === 404) {
  // Render the missing-resource page. Other errors require their own state.
}

import {errorCode} from "@behio/storefront-sdk";

const {error} = await storefront.catalog.getProducts({limit: 12});
if (errorCode(error) === "be.storefront.siteKeyNotAllowed") {
  // Website without a shop: render the site without the catalog.
}

import { BehioStorefront } from "@behio/storefront-sdk";

const storefront = new BehioStorefront({
  apiKey: "pk_live_xxx",
  retries: 2,       // Number of retries (default: 1)
  retryDelay: 1000,  // Base delay in ms (default: 1000)
  timeout: 30000,    // Request timeout in ms (default: 30000)
});

const storefront = new BehioStorefront({
  apiKey: "pk_live_xxx",
  throwOnAvailabilityError: true,
});

// Listen for refresh failures to redirect to login
storefront.on("auth:token-refresh-failed", () => {
  // Tokens have been cleared automatically
  router.push("/login");
});

storefront.on("auth:token-refresh", () => {
  // Optional: persist the new tokens
  const accessToken = storefront.getAccessToken();
  const refreshToken = storefront.getRefreshToken();
  localStorage.setItem("tokens", JSON.stringify({ accessToken, refreshToken }));
});

const info = storefront.getRateLimitInfo();
console.log(info.remaining); // Requests remaining (null if no response yet)
console.log(info.reset);     // Unix timestamp when the limit resets

storefront.on("rate-limit-warning", (data) => {
  const { remaining, reset } = data as { remaining: number; reset: number };
  console.warn(`Rate limit low: ${remaining} requests remaining`);
  console.warn(`Resets at: ${new Date(reset * 1000).toISOString()}`);
});

import { useProduct } from "@behio/storefront-sdk/react";
import { BehioApiError } from "@behio/storefront-sdk";

function ProductPage({ slug }: { slug: string }) {
  const { data, error, isLoading } = useProduct(slug);

  if (isLoading) return <div>Loading...</div>;

  if (error) {
    if (error instanceof BehioApiError && error.is("NOT_FOUND")) {
      return <div>Product not found</div>;
    }
    return <div>Something went wrong: {error.message}</div>;
  }

  return <h1>{data.name}</h1>;
}

import { useCart } from "@behio/storefront-sdk/react";
import { BehioApiError } from "@behio/storefront-sdk";

function AddToCartButton({ productId }: { productId: string }) {
  const { addItem } = useCart();

  const handleAdd = async () => {
    try {
      await addItem.mutateAsync({ productId, quantity: 1 });
    } catch (error) {
      if (error instanceof BehioApiError) {
        if (error.is("PRODUCT_NOT_FOUND")) {
          showToast("This product is no longer available");
        } else if (error.is("VALIDATION_ERROR")) {
          showToast("Invalid quantity");
        }
      }
    }
  };

  return <button onClick={handleAdd}>Add to Cart</button>;
}

storefront.on("error", (error) => {
  // Send to error tracking (Sentry, etc.)
  console.error("[Behio SDK]", error);
});

import { QueryErrorResetBoundary } from "@tanstack/react-query";
import { ErrorBoundary } from "react-error-boundary";

function App() {
  return (
    <QueryErrorResetBoundary>
      {({ reset }) => (
        <ErrorBoundary
          onReset={reset}
          fallbackRender={({ error, resetErrorBoundary }) => (
            <div>
              <p>Something went wrong: {error.message}</p>
              <button onClick={resetErrorBoundary}>Try again</button>
            </div>
          )}
        >
          <ShopContent />
        </ErrorBoundary>
      )}
    </QueryErrorResetBoundary>
  );
}

import { BehioApiError, type BehioErrorCode } from "@behio/storefront-sdk";

const errorMessages: Partial<Record<BehioErrorCode, string>> = {
  UNAUTHORIZED: "Please log in to continue",
  NOT_FOUND: "The requested item was not found",
  VALIDATION_ERROR: "Please check your input",
  RATE_LIMITED: "Too many requests, please wait",
  CART_EMPTY: "Your cart is empty",
  INVALID_CREDENTIALS: "Wrong email or password",
  INVALID_DISCOUNT: "This discount code is invalid",
  DISCOUNT_EXPIRED: "This discount code has expired",
  EMAIL_ALREADY_EXISTS: "An account with this email already exists",
  INTERNAL_ERROR: "Server error, please try again later",
};

function getErrorMessage(error: unknown): string {
  if (error instanceof BehioApiError) {
    return errorMessages[error.code] ?? error.message;
  }
  if (error instanceof Error) {
    return error.message;
  }
  return "An unexpected error occurred";
}