Skip to content

Errors in the SDK

This page shows what the SDK throws when a request fails, which codes to branch on and how to turn a code into text for a shopper. For the error bodies the API sends and which statuses are safe to retry, see the errors guide.

The HTTP client returns an ApiResponse with success set to false and an error that holds message, statusCode, the API’s code and details. Most API class methods pass that response through unwrap or unwrapOrNull, which turn a failure into an exception.

Helper On success On a failure
unwrap Returns the data Throws an ApiClientError
unwrapOrNull Returns the data Returns null for a 404, and throws an ApiClientError for every other error
ensureSuccess Returns nothing Throws an ApiClientError

ApiClientError has message, statusCode, code and details. code is the API’s stable error code and is what you branch on. message is the API’s English text and is not meant for shoppers. A request that never got an answer has statusCode 0, and its code is the network error, such as ECONNABORTED for a timeout or ERR_NETWORK.

import { ApiClientError } from "@ecomweb/sdk";
import { sdk } from "@ecomweb/storefront-kit";
try {
const product = await sdk.products.getById("my-store", 12);
if (!product) console.log("No such product");
} catch (error) {
if (error instanceof ApiClientError && error.statusCode === 403) {
console.log(error.code, error.details);
} else {
throw error;
}
}

A method such as products.getById, cart.getCart or stores.getById returns null for a missing item, so a 404 there is not an exception. Check for null before you read the result. The 404 list is the helper’s nullStatusCodes argument, and it defaults to [404].

Two hooks never throw. useCart reports a failed call through the provider’s onNotice, and useCheckout().placeOrder returns an error result with a code. See Cart and checkout.

These are the values of AuthErrorCode. Branch on them and write your own text.

Code When it happens
AUTH_INVALID_CREDENTIALS The email or password is wrong
AUTH_ACCOUNT_LOCKED Too many failed attempts
AUTH_ACCOUNT_DISABLED The merchant marked the customer inactive (403)
AUTH_EMAIL_NOT_VERIFIED The store requires a verified email first
AUTH_METHOD_DISABLED The store turned this sign-in method off
AUTH_TOKEN_INVALID A verification, reset or sign-in code is wrong or already used
AUTH_TOKEN_EXPIRED The code or link has expired
AUTH_SESSION_EXPIRED The session ended, so sign in again
AUTH_WEAK_PASSWORD The password does not meet the store’s policy
AUTH_RATE_LIMITED Too many requests
AUTH_STORE_MISMATCH The session belongs to another store
AUTH_EMAIL_TAKEN An account already uses this email

errorCopy turns a code into shopper text, and errorCopyFor does the same for anything you caught. It uses the code first and the HTTP status second. It never uses the API’s message.

import { errorCopy, errorCopyFor } from "@ecomweb/storefront-kit";
errorCopy("AUTH_EMAIL_TAKEN"); // "Email này đã được sử dụng."
errorCopy("UNKNOWN_CODE", "Something went wrong."); // your fallback
errorCopyFor(caughtError); // reads code and statusCode

errorCopy knows the auth codes above and these: ACCESS_DENIED, VALIDATION_FAILED, ADDRESS_NOT_FOUND, ORDER_NOT_FOUND, ORDER_NOT_CANCELLABLE, INSUFFICIENT_INVENTORY, ORDER_PROMOTION_NOT_APPLICABLE, PROMOTION_USAGE_LIMIT_REACHED, PROMOTION_IDENTITY_REQUIRED, SHIPPING_QUOTE_CHANGED, ORDER_SHIPPING_RATE_UNAVAILABLE, ORDER_CANCEL_BLOCKED_BY_SHIPMENT, STORE_COMING_SOON and BLOG_COMMENTS_DISABLED. For a code it does not know, it returns the fallback you pass, or a generic Vietnamese sentence. Without a code, errorCopyFor uses the status. It has text for 0, 401, 403, 404, 429, 500, 502, 503 and 504.

A store can be closed to shoppers in two ways, and both show up as errors on the first read, usually getCachedStore.

State What the API answers Helper
Suspended by the platform 403 STORE_SUSPENDED isStoreSuspendedError
Coming soon, not opened by the merchant yet 403 STORE_COMING_SOON with details.name isStoreComingSoonError, comingSoonStoreNameOf
Missing or not active 404 STORE_UNAVAILABLE getCachedStore returns null
import { comingSoonStoreNameOf, getCachedStore, isStoreComingSoonError } from "@ecomweb/storefront-kit";
try {
const store = await getCachedStore(storeRef);
} catch (error) {
if (isStoreComingSoonError(error)) return <p>{comingSoonStoreNameOf(error)} opens soon</p>;
throw error;
}

The kit’s middleware already rewrites a coming soon store to /coming-soon, and a browser call that meets either error goes to /coming-soon or /store-suspended. Your app owns the /coming-soon page. Call resolveComingSoonStore for the store name and return comingSoonStoreMetadata so search engines skip it. withSuspendedStoreMetadataFallback wraps a generateMetadata function and returns the right metadata for either state.

The merchant sees the real store through a preview link from the dashboard. A preview is read-only, so the API opens only GET and HEAD requests. In a preview, cart writes and placeOrder are refused with a notice, and placeOrder returns STORE_PREVIEW_READ_ONLY_MESSAGE. Show that message as it is. Needs kit 0.11.0 or later.

Method What it does
unwrap Returns the data or throws an ApiClientError
unwrapOrNull Returns the data, null for a 404, or throws
ApiClientError The error the SDK throws, with statusCode, code and details
errorCopy Shopper text for an error code
errorCopyFor Shopper text for a caught error
isStoreComingSoonError Whether an error means the store is coming soon
isStoreSuspendedError Whether an error means the store is suspended
resolveComingSoonStore Tells your /coming-soon page the store name