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.
What the SDK throws
Section titled “What the SDK throws”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.
Auth error codes
Section titled “Auth error codes”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 |
Showing errors to shoppers
Section titled “Showing errors to shoppers”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 fallbackerrorCopyFor(caughtError); // reads code and statusCodeerrorCopy 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.
Store states
Section titled “Store states”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.
Key methods
Section titled “Key methods”| 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 |