Limits

Kustom limits both how often you may call and how large a single call may be. Rate limits are counted per merchant ID, not per credential, so every server, job and retry you run shares one quota. Every response tells you how much of that quota is left, which is what lets a well-behaved client pace itself instead of discovering the limit by hitting it.

Rate limits per merchant ID

Limits are measured per operation class. Creating a session is metered separately from everything else, because it is the expensive one.

Environment	Create-session operations	All other operations
Production	40 requests per second	200 requests per second
Playground (testing)	5 requests per second	50 requests per second

Two things follow from “per merchant ID”. Issuing a second set of API credentials does not buy you more quota. And once a merchant ID is being rate limited, every subsequent request from that merchant is rejected until the window resets — including requests from a different service of yours that was behaving perfectly.

Creating a customer token is metered as a create-session operation: 40 per second in production, 5 per second in playground.

Kustom may change these limits to prevent abuse or to contain a misbehaving integration. Read the headers rather than hard-coding the numbers above.

Rate limit headers on every response

Three headers accompany every response, not only a rejected one.

Header	What it reports
X-Ratelimit-Limit	The quota and the metering window, as <quota>, <quota>;w=<seconds>.
X-Ratelimit-Remaining	Approximate requests still available in the current window.
X-Ratelimit-Reset	Seconds until the current window resets.

X-Ratelimit-Limit: 40, 40;w=1
X-Ratelimit-Remaining: 15
X-Ratelimit-Reset: 1

That response says the quota is 40 requests per 1-second window, 15 remain in the current window, and the window resets in 1 second. The values are approximate and best-effort — treat Remaining as a signal to slow down, never as an exact budget to spend to zero.

Handling a 429

A rate-limited request returns HTTP 429 and the headers above. Recovering from one well takes three things:

1. Pace against X-Ratelimit-Remaining. Slow down as it approaches zero rather than waiting for the rejection. Spread a batch job across the whole window instead of firing it at the top of the second.
2. Retry with exponential backoff plus jitter. Without jitter, every client that was throttled together retries together, and throttles itself again.
3. Control global flow with a token bucket. One shared bucket in front of your Kustom client caps the rate across all your workers, which per-worker limits cannot do.

A 429 means “not now”, not “invalid” — the request itself was fine, so retrying it is safe. On an Order Management write, send an idempotency key anyway. See Idempotency and retries.

Request body size limit

The maximum request body is 1MB by default. A larger body is not processed and returns 413 Payload Too Large.

This bites in exactly one place in practice: an order with a very long order-line list, or a large attachment.body of extra merchant data. Neither gets truncated for you — the whole request is rejected.

Common causes of rate limiting

Cause	What to do about it
A burst of requests in a short window	Pace requests across the full interval the headers report, and retry with exponential backoff.
A planned traffic spike, such as a flash sale	Contact Kustom Merchant Support before the event, not during it.
Bot traffic against your storefront	Add bot detection and require user authentication before your server calls Kustom.

Quotas are set so that legitimate traffic from the large majority of merchants never touches them. If you are hitting a limit routinely, the shape of the traffic is worth investigating before the quota is.

Related

• Reading the 429 error body — the error object and its correlation_id
• Retrying a write safely — the idempotency key that makes a retry cost nothing
• Trimming a request that returns 413 — where large attachment bodies come from
• Checking Kustom’s current status — availability objectives and the status page