Rate limits

Request limits of the merchant API, the rate-limit headers and how to handle 429 responses.

Limit	Value
Requests per API key	600 per minute
Requests per test key	60 per minute
Catalog Push API batches	120 per minute per store
Order reports	60 per minute per store
Privacy requests	100 per day per store

Every response of a limited endpoint carries X-RateLimit-Limit and X-RateLimit-Remaining. When you exceed a limit you get 429 rate_limited with a Retry-After header (seconds) and details.retry_after_seconds.

{
  "error": {
    "code": "rate_limited",
    "message": "Too many requests.",
    "details": { "scope": "api_key", "retry_after_seconds": 12 },
    "request_id": "req_…"
  }
}

Wait for Retry-After, then retry. For bulk work, spread requests evenly instead of sending bursts.