Rate limits

Overview

The Katura API enforces rate limits to ensure fair usage and platform stability.

Current rate limits

Rate limit headers

Every API response includes rate limit headers:

• X-RateLimit-Limit — maximum requests per window
• X-RateLimit-Remaining — requests remaining in window
• X-RateLimit-Reset — timestamp when window resets

Pagination

List endpoints use cursor-based pagination:

• page — page number (default: 1)
• limit — items per page (default: 20, max: 100)
• Response includes total, page, and totalPages

Handling 429 responses

When you hit the limit, the API returns 429 with a Retry-After header (seconds). Honor it. The reference client below uses exponential backoff with full jitter — a sane default for any production integration:

async function katuraFetch(url, init = {}, attempt = 0) {
  const res = await fetch(url, init);
  if (res.status !== 429 || attempt >= 5) return res;

  const retryAfter = Number(res.headers.get("Retry-After")) || (2 ** attempt);
  const jitter = Math.random() * retryAfter;
  await new Promise(r => setTimeout(r, (retryAfter + jitter) * 1000));
  return katuraFetch(url, init, attempt + 1);
}

Bursts & bulk imports

For one-time backfills (e.g., importing 10k products), use POST /api/admin/products/importinstead of looping single creates — bulk endpoints don't count individual items against the per-minute limit. For sustained higher throughput, contact support to lift the cap on a specific API key.

Related

• API overview
• Webhooks (no rate limit on outbound)