Quota and cache

Each key has 60 requests per minute; past that, the API returns 429 with how long to wait. Cache recommendations by context and don’t spend the quota twice on the same thing.

How it’s counted

It’s counted per key, after authentication. A request without a key spends nobody’s quota.
The budget refills gradually, not per fixed window.
Past the budget, the response is 429 rate_limited with Retry-After in seconds.

// If you call the API yourself, the status and the header are enough.
if (res.status === 429) {
  const wait = Number(res.headers.get("Retry-After") ?? 1); // seconds
  // don't retry sooner; and find the loop that caused it
}

// A 429 says how long to wait.
if resp.StatusCode == http.StatusTooManyRequests {
    wait, _ := strconv.Atoi(resp.Header.Get("Retry-After")) // seconds
    _ = wait // no recommendation for now; the page goes on
}

What to do with a 429

Wait what Retry-After says, no less.
Don’t retry in a loop. The SDK doesn’t retry a recommendations request on its own: tryGetRecommendations returns null and the page goes on. Signals are retried, with growing backoff.
Find the loop. It’s almost always a render that repeats: an effect without dependencies, an observer that fires several times, a request per card.

What to cache

A recommendation is valid for as long as the view lasts. Caching it saves quota, and the shopper sees the same list when going back.

What	Cache key	For how long
A product page recommendation	`surface + placement_key + context_item_id`	The page session; a few minutes at most
A cart recommendation	`surface + placement_key + hash(cart_items)`	Until the cart changes
A catalog product	`item_id`	Minutes: price and stock change

Don’t cache an empty response because the engine didn’t answer: it can come back in seconds. Nor a recommendation beyond the session: decision_id (the recommendation’s id) ties the signals, and a stale recommendation misattributes.

What you will see

A 429 carries Retry-After and a request_id. With those and the Network tab you find the request that repeats.

If you don’t see it

What happens	What to do
`429` in production with normal traffic	One request per card spends N per page. Request a single recommendation for the listing
`429` in load tests	That’s expected: use several keys or the local environment
No `Retry-After`	A proxy stripped it. Wait one second

Keys and security

Why the quota is part of the key’s security.

Errors

Every API error, with its code and what to do.

​How it’s counted

​What to do with a 429

​What to cache

​What you will see

​If you don’t see it