> For the complete documentation index, see [llms.txt](https://docs.peakcommerce.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.peakcommerce.com/developers/api-reference/rate-limits.md).

# 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](https://gitlab.com/peakcommerce/peak-help-docs/-/tree/main/product/settings/observability/api-usage.md), 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](https://docs.peakcommerce.com/developers/admin-api/admin-api-keys.md) 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:**

```json
{
  "error": { "code": "rate_limit_exceeded", "message": "Rate limit exceeded. Try again later." },
  "requestId": "req_..."
}
```

`X-RateLimit-Reset` tells you when the key's window resets. Wait until then, then retry.

**Your tenant over one of its limits:**

```json
{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Tenant has exceeded the API RPM limit. Retry after 12 seconds.",
    "limit_type": "API",
    "retry_after_seconds": 12
  }
}
```

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.

## Related

* [Authentication](https://docs.peakcommerce.com/developers/api-reference/authentication.md)
* [Errors](https://docs.peakcommerce.com/developers/api-reference/errors.md)
* [API Usage](https://gitlab.com/peakcommerce/peak-help-docs/-/tree/main/product/settings/observability/api-usage.md) — your tenant's limits and how close you are to them


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.peakcommerce.com/developers/api-reference/rate-limits.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
