Error Handling

ShopiError

All SDK errors are instances of ShopiError. Use instanceof to catch them cleanly.

import { Shopi, ShopiError } from '@shopi-lk/storefront-sdk';

try {
  const product = await shop.products.getBySlug('missing-product');
} catch (error) {
  if (error instanceof ShopiError) {
    console.error(error.message); // human-readable message
    console.error(error.status);  // HTTP status code
    console.error(error.data);    // raw response body
  }
}

Status codes

Status	Meaning	What to do
`0`	Network error — offline, DNS failure	Check connectivity, retry
`401`	Invalid or missing API key	Check the key starts with `shopi_pk_`
`403`	Key does not have required scope	Contact shop owner to regenerate key
`404`	Resource not found	Check slug or ID is correct
`408`	Request timed out	Increase `timeoutMs` or retry
`429`	Rate limit exceeded	Wait for `Retry-After` seconds
`500`	Server error	Retry with backoff
`502`	Upstream unavailable	Retry — transient infrastructure issue

Automatic retries

The SDK automatically retries 500, 502, 503, 504, and 429 responses up to 2 times with exponential backoff (300ms, then 600ms). You do not need to implement retry logic yourself. For 429 responses, the SDK reads the Retry-After header and waits the correct amount of time before retrying.

Timeout

Every request times out after 10 seconds by default. A timed-out request throws ShopiError with status: 408.

// Increase timeout for slow connections
const shop = new Shopi({
  apiKey: process.env.SHOPI_API_KEY!,
  timeoutMs: 20000, // 20 seconds
});

Full error handling example

import { Shopi, ShopiError } from '@shopi-lk/storefront-sdk';

const shop = new Shopi({ apiKey: process.env.SHOPI_API_KEY! });

async function getProduct(slug: string) {
  try {
    return await shop.products.getBySlug(slug);
  } catch (error) {
    if (error instanceof ShopiError) {
      switch (error.status) {
        case 404:
          return null; // product doesn't exist
        case 401:
          throw new Error('Invalid API key — check your configuration');
        case 429:
          throw new Error('Too many requests — slow down');
        case 0:
          throw new Error('No internet connection');
        default:
          throw new Error(`API error ${error.status}: ${error.message}`);
      }
    }
    throw error; // re-throw unexpected errors
  }
}

​ShopiError

​Status codes

​Automatic retries

​Timeout

​Full error handling example

ShopiError

Status codes

Automatic retries

Timeout

Full error handling example