Fix Katana API 429 Too Many Requests

How to stop the 429 errors

1. 1Log the full response of a failing call: status, body and every header. Look for a Retry-After header or rate-limit remaining and reset headers.
2. 2Stop retrying immediately in a tight loop. On 429, sleep for the Retry-After value if present, otherwise use exponential backoff (1s, 2s, 4s, 8s) with random jitter.
3. 3Find the loop that creates the volume: usually one call per sales order, per variant or per stock row. Replace it with list endpoints using filters and the largest page size the API allows.
4. 4Cache slow-changing reference data (products, variants, materials, locations) locally and refresh it on a schedule instead of fetching it per transaction.
5. 5Sync incrementally using an updated-at filter or the last processed ID instead of re-reading everything on every run.
6. 6Serialize calls through one queue or worker per API key. Several parallel workers sharing one key share one allowance.
7. 7If a middleware tool (Zapier, Make, a Shopify connector) is also calling Katana with the same key, count its traffic too or give each integration its own key.
8. 8Add a metric for 429 count per hour so you notice regressions before an order sync silently falls behind.

A retry wrapper that behaves

async function katanaFetch(url, opts, attempt = 0) {
  const res = await fetch(url, opts);
  if (res.status !== 429 && res.status < 500) return res;
  if (attempt >= 5) throw new Error('Katana API retry limit: ' + res.status);
  const hinted = Number(res.headers.get('retry-after'));
  const base = hinted > 0 ? hinted * 1000 : 1000 * 2 ** attempt;
  const wait = base + Math.random() * 500;
  await new Promise(r => setTimeout(r, wait));
  return katanaFetch(url, opts, attempt + 1);
}

Shared keys and middleware

Common pitfalls

• !Retrying instantly in a loop, which keeps you permanently rate limited and can look like abuse.
• !Retrying 400 or 422 responses as if they were rate limits. Fix the payload instead.
• !Running several parallel workers on one key and tuning each one as if it had the whole allowance.
• !Assuming a POST that got 429 partly succeeded. It did not, but a POST that timed out might have, so use your own idempotency check before re-creating orders.
• !Hard-coding a request limit from a blog post. Read the current limits and headers from Katana's documentation and responses.