Rate limits

The API rate limits requests per API key using a fixed one-minute window.

• Default: 60 requests/minute per key (configurable per key).
• Window: fixed, 1 minute.

When you're limited

Exceeding the limit returns 429 with a Retry-After header (seconds):

HTTP/1.1 429 Too Many Requests
Retry-After: 23
Content-Type: application/json

{ "error": "Rate limit exceeded", "code": "RATE_LIMITED" }

Backing off

With the SDK, use the typed guard and retryAfter:

import { isRateLimited } from "@usestorekit/sdk";

const { data, error } = await storekit.products.list();
if (isRateLimited(error)) {
  const waitMs = (error.retryAfter ?? 1) * 1000;
  await new Promise((r) => setTimeout(r, waitMs));
  // …then retry
}

OTP throttle

Login OTPs have a separate, stricter throttle independent of the request limit: a phone number can request at most 5 OTPs per hour per store. Exceeding it returns an error from POST /v1/auth/otp/request.

Tips to stay under the limit

• Let the Next.js adapter cache public catalog reads (it does by default) so repeated page loads don't re-hit the API.
• Use products.listAll() / pagination with a sensible limit instead of many tiny requests.
• Batch UI updates rather than firing a request per keystroke (debounce search).