Rate limits
Two kinds of limit apply to API calls:
Per-key limits — every API key has a rate-limit tier that caps its requests per minute.
Your tenant's limits — the rate and concurrency limits shown on API Usage, shared by everything that calls PeakCommerce for your tenant.
A request must fit within both.
Per-key tiers
Each key's count runs in a fixed 60-second window that starts with the key's first request and resets when the window ends.
standard
60
premium
300
unlimited
10,000
Keys created in Settings → API Keys start on standard. A key created through the admin API can be given another tier, or your account team can change it.
Headers
Every response to an API-key request includes:
X-RateLimit-Limit
Your bucket's max for the current window
X-RateLimit-Remaining
Requests left in the current window
X-RateLimit-Reset
Unix timestamp (seconds) when the bucket resets
When you exceed a limit
You get 429 Too Many Requests with the standard error envelope.
A key over its tier:
X-RateLimit-Reset tells you when the key's window resets. Wait until then, then retry.
Your tenant over one of its limits:
A rate limit sends a Retry-After header with the same number of seconds. If too many calls are running at once, the code is concurrency_limit_exceeded and limit_type names the concurrency bucket (Default, Query or High-volume); retry after a second.
Branch on error.code, not the message text.
Best practices
Honor
Retry-Afterwhen present, and back off before retrying — a burst of immediate retries counts against the same limits.Cache
GET /api/v1/manifest,/catalog,/capabilities, and/pricing/resolveresponses for at least 60 seconds — they don't change often.For batch jobs, prefer fewer, larger calls — use filter parameters (e.g.
?status=active,?accountId=...) on list endpoints to fetch the rows you need in one request rather than many small ones.Webhook deliveries do not consume your API rate limit.
Raising a limit
Ask your account team to raise a key's tier or your tenant's limits. Tell them your expected requests per second and burst pattern, and they will right-size the limit.
Related
API Usage — your tenant's limits and how close you are to them
Last updated
Was this helpful?
