Rate Limiting

What you'll learn

How API rate limiting works
How to handle rate limit responses
Best practices for efficient API usage

Rate Limits

The API applies rate limiting to protect service availability. Limits are applied per IP address and per store.

When you exceed the rate limit, the API returns a 429 Too Many Requests response.

Handling Rate Limits

When you receive a 429 response:

Read the Retry-After header (seconds to wait)
Wait for the specified duration
Retry the request

Example Response

HTTP/1.1 429 Too Many Requests
Retry-After: 30
Content-Type: application/vnd.api+json

{
  "errors": [{ "status": "429", "detail": "Rate limit exceeded. Try again in 30 seconds." }]
}

JavaScript Retry Example

async function fetchWithRetry(url, options, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const response = await fetch(url, options);

    if (response.status === 429) {
      const retryAfter = parseInt(
        response.headers.get("Retry-After") || "30",
        10,
      );
      console.warn(`Rate limited. Retrying in ${retryAfter}s...`);
      await new Promise((resolve) => setTimeout(resolve, retryAfter * 1000));
      continue;
    }

    return response;
  }
  throw new Error("Max retries exceeded");
}

Best Practices

Cache aggressively

Product catalog data changes infrequently. Cache responses for:

Store details: 5–15 minutes
Products list: 1–5 minutes
Categories, brands, filters, types, tags: 5–15 minutes
Product detail: 1–5 minutes

Minimize requests

Use the filters endpoint (GET /api/v2/products/filters) once on page load, not on every filter change
Fetch categories and brands once and cache locally
Use limit and offset efficiently — don't fetch all products at once

Use conditional requests

Where supported, use If-None-Match / ETag headers to avoid re-downloading unchanged data.

Batch client-side operations

When adding multiple items to a cart, batch rapid changes rather than sending one request per item click.

API Versioning