For the complete documentation index, see llms.txt. This page is also available as Markdown.

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.

Tier
Requests per minute

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:

Header
Meaning

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-After when 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/resolve responses 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.

Last updated

Was this helpful?