Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.shopi.lk/llms.txt

Use this file to discover all available pages before exploring further.

​
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

StatusMeaningWhat to do
0Network error — offline, DNS failureCheck connectivity, retry
401Invalid or missing API keyCheck the key starts with shopi_pk_
403Key does not have required scopeContact shop owner to regenerate key
404Resource not foundCheck slug or ID is correct
408Request timed outIncrease timeoutMs or retry
429Rate limit exceededWait for Retry-After seconds
500Server errorRetry with backoff
502Upstream unavailableRetry — 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
  }
}