Rate limits

Headers

Every response tells you where you stand:

Requests over the limit answer 429 with code rate_limited and are not counted. The MCP server shares the key's budget.

Retrying

async function request(url, init, attempt = 0) {
  const res = await fetch(url, init);
  if (res.status === 429 && attempt < 5) {
    const wait = Number(res.headers.get("retry-after") ?? 1);
    await new Promise((r) => setTimeout(r, wait * 1000));
    return request(url, init, attempt + 1);
  }
  if (res.status >= 500 && attempt < 5) {
    await new Promise((r) => setTimeout(r, 2 ** attempt * 500));
    return request(url, init, attempt + 1);
  }
  return res;
}

Staying well under the limit

• Write in batches: POST /products/bulk takes up to 500 products per request.
• Read in pages of 250 and only what changed: updated_since instead of full re-reads.
• Use If-None-Match when polling single products — 304 answers are fast (they still count as requests).
• Use webhooks instead of polling for changes.
• For whole-catalog files use exports or pull feeds rather than paging through the API.