Error handling

The SDK uses a Result pattern. All methods return { data, error } instead of throwing exceptions.

Result pattern

import { createSDK, ApiError } from '@commerce-blocks/sdk'

const { data: sdk, error: initError } = createSDK({
  storefrontAccessToken: 'your-storefront-token',
  trackingToken: 'your-tracking-token',
})

if (initError) {
  console.error('SDK init failed:', initError.message)
}

const collection = sdk.collection({ collectionHandle: 'shirts' })
const { data, error } = await collection.get()

if (error) {
  if (error instanceof ApiError) {
    console.error('HTTP', error.status, error.statusText)
    console.error('Response body:', error.body)
  } else {
    console.error('SDK error:', error.message)
  }
} else if (data) {
  renderProducts(data.products)
}

Error types

The SDK produces two kinds of errors:

Error instances for network failures, timeouts, aborted requests, and unexpected thrown values.
ApiError instances for HTTP responses that return a non-2xx status.

ApiError

An ApiError is returned when the Layers API responds with an error status. It has the following fields:

Field	Type	Description
`status`	`number`	HTTP status code
`statusText`	`string`	HTTP status text
`message`	`string`	Human-readable description
`body`	`unknown`	Parsed JSON body, raw text, or `undefined`

import { ApiError } from '@commerce-blocks/sdk'

const { error } = await collection.get()

if (error instanceof ApiError) {
  if (error.status === 401) {
    showError('The storefront token is missing or invalid.')
  } else if (error.status === 429) {
    showError('Too many requests. Please wait a moment and try again.')
  } else {
    showError('The server returned an error. Please try again.')
  }
}

ConfigError

A ConfigError is an Error subclass returned during createSDK() when the SDK is misconfigured or used in an unsupported environment. A storage-related error occurs only when you pass a storage value in an environment without localStorage; the SDK does not access localStorage on its own. ConfigError is not exported, so match on error.name === 'ConfigError' or handle error directly.

import { createSDK } from '@commerce-blocks/sdk'

const { data: sdk, error } = createSDK({
  storefrontAccessToken: 'your-storefront-token',
  trackingToken: 'your-tracking-token',
  storage: customStorage, // use when prepared search IDs need persistence
})

if (error) {
  console.error('SDK could not start:', error.message)
}

Error handling with reactive state

Use subscribe to react to loading, errors, and data changes in any framework:

const collection = sdk.collection({ collectionHandle: 'shirts' })

collection.subscribe(({ data, error, loading }) => {
  if (loading) {
    showLoading()
    return
  }

  if (error) {
    if (error instanceof ApiError && error.status === 401) {
      showError('Storefront token is invalid.')
    } else {
      showError('Something went wrong. Please try again.')
    }
    return
  }

  if (!data || data.products.length === 0) {
    showEmpty('No products found.')
    return
  }

  renderProducts(data.products)
})

await collection.get()

Retry behavior

The search controller automatically prepares queries and retries a 425 “not prepared yet” response. Most other controllers do not retry by default. To add retry logic, wrap the get() call in your own loop and use error.cause to inspect the original failure.

async function getWithRetry(controller, retries = 3) {
  for (let i = 0; i < retries; i++) {
    const { data, error } = await controller.get()
    if (!error) return { data, error: null }
    if (i === retries - 1) return { data, error }
    await new Promise((resolve) => setTimeout(resolve, 1000 * (i + 1)))
  }
}

Common errors and fixes

Symptom	Cause	Fix
`401 Unauthorized`	Missing or invalid `storefrontAccessToken`	Confirm the token in `createSDK()` or the Shopify `shop.metafields.layers.embed_settings.value.storefrontApiToken` metafield.
`"The selected sort order code is invalid."`	The `sort` value does not match a configured sort order	Fetch sort orders with `sdk.sortOrders()` and use a valid `code`.
`"The selected facet is invalid."`	A filter references an attribute not configured as a facet	Fetch facets with `sdk.facets({ collectionHandle })` and use valid attribute codes.
Network `TypeError` or `Failed to fetch`	Browser extension, ad blocker, or missing `fetch`	Try `fetch: xhrFetch` or check the network tab.

For token and metafield issues, see the Troubleshooting section in Installation.

Overview

SDK Reference

SDK Guides

Changelog & Upgrades

AI Enablement

Error handling

Result pattern

Error types

ApiError

ConfigError

Error handling with reactive state

Retry behavior

Common errors and fixes

Next steps

​Result pattern

​Error types

​ApiError

​ConfigError

​Error handling with reactive state

​Retry behavior

​Common errors and fixes

​Next steps

Result pattern

Error types

ApiError

ConfigError

Error handling with reactive state

Retry behavior

Common errors and fixes

Next steps