Handle errors from the Quickshops TypeScript SDK gracefully

Every failed TypeScript SDK call throws a QuickshopsError. Because the SDK wraps all network communication, you get a consistent error shape regardless of whether the failure is an authentication problem, a rate limit, or a missing resource. Catching errors by type lets you respond precisely without parsing raw HTTP responses.

The `QuickshopsError` class

QuickshopsError extends the native Error class and adds HTTP metadata:

Field	Type	Description
`message`	`string`	Human-readable description of the error
`statusCode`	`number`	HTTP status code returned by the API
`body`	`string`	Raw response body (often JSON with `code` and `message`)
`headers`	`Headers`	Response headers, including `x-request-id` when present

Import QuickshopsError from @quickshops/sdk/models/errors. Import the client from @quickshops/sdk in server-only modules.

Catching errors

Use instanceof to distinguish SDK errors from other thrown values.

import { qs } from "@/lib/quickshops";
import { QuickshopsError } from "@quickshops/sdk/models/errors";

try {
  const { data: products } = await qs.products.productsGetAll();
} catch (err) {
  if (err instanceof QuickshopsError) {
    console.error(err.statusCode, err.message, err.body);
  }
}

Common error codes

Parse err.body as JSON when you need machine-readable codes:

Status	Typical code	Cause
`401`	`UNAUTHORIZED`	Your API key is missing, malformed, or has been revoked
`403`	`FORBIDDEN`	The key is not allowed for this route, the request origin is blocked, or the store is not on Pro
`429`	`RATE_LIMITED`	Your requests have exceeded the allowed rate; back off and retry
`404`	`NOT_FOUND`	The requested resource (product, cart, etc.) does not exist
`409`	`CONFLICT`	A duplicate server-side request is already in progress
`400`	`INVALID_REQUEST`	The request payload is invalid

Handling errors by status

You can branch on err.statusCode to respond differently to each condition.

import { qs } from "@/lib/quickshops";
import { QuickshopsError } from "@quickshops/sdk/models/errors";

async function loadProducts() {
  try {
    const { data } = await qs.products.productsGetAll();
    return data;
  } catch (err) {
    if (err instanceof QuickshopsError) {
      if (err.statusCode === 401) {
        throw new Error("Store configuration error");
      }
      if (err.statusCode === 429) {
        throw new Error("Too many requests, please try again shortly");
      }
      if (err.statusCode === 404) {
        return null;
      }
    }
    throw err;
  }
}

Include err.headers.get("x-request-id") in support requests. It uniquely identifies the failed API call on the server.

Get Started

Your Store

Products & Sales

Integrations

Developers

Handle errors from the Quickshops TypeScript SDK gracefully

The `QuickshopsError` class

Catching errors

Common error codes

Handling errors by status

​The QuickshopsError class

​Catching errors

​Common error codes

​Handling errors by status

The `QuickshopsError` class

Catching errors

Common error codes

Handling errors by status