> ## Documentation Index
> Fetch the complete documentation index at: https://developer.clopos.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Rate limits

> Request quotas, response headers, and how to handle throttling on Clopos Open API v2

# Rate limits

Clopos Open API v2 applies a **three-tier rate limit**, each with a 1-minute sliding window and standard IETF `RateLimit-*` response headers. The tiers layer so that an abusive client IP, a flood of invalid tokens, and a noisy tenant each hit their own ceiling without starving the others.

## The three tiers

### Tier 1 — Auth endpoint

<Info>
  **60 requests per minute per client IP**, applied to `POST /v2/auth` only.
</Info>

This is a brute-force guard on credential exchange. It applies per client IP regardless of which `integrator_id` or `brand` is in the body. Re-use issued tokens until they are close to `expires_at` rather than calling `/v2/auth` on every request — you will exhaust this quota quickly if you do not.

### Tier 2 — IP pre-limit (flood guard)

<Info>
  **600 failed requests per minute per client IP**, applied to all authenticated routes.
</Info>

This tier runs **before** JWT validation and only counts responses with HTTP status **≥ 400**. Successful requests do not decrement the counter at all. It exists to stop invalid-token spam and similar flood patterns without capping legitimate traffic from integrators that fan many brands through a single outbound IP.

In practice, you will only see this limit if your client is repeatedly sending malformed, expired, or unauthorized requests from the same IP. Fix the request and it stops counting.

### Tier 3 — Per-tenant limit

<Info>
  **300 requests per minute per `integrator_id:brand` pair**, applied to all authenticated routes.
</Info>

This is the main quota you will plan against. It runs **after** JWT validation and keys on the verified JWT payload, so:

* Minting new tokens for the same `(integrator_id, brand)` does **not** reset the counter — all tokens share the same budget.
* The budget is per `(integrator_id, brand)` pair. A single integrator serving many brands gets a separate 300 req/min budget for each brand.
* Distributing traffic across many workers or processes does not multiply the quota — the limit is enforced centrally.

## Response headers

Every authenticated response includes standard [IETF `RateLimit-*` headers](https://datatracker.ietf.org/doc/draft-ietf-httpapi-ratelimit-headers/) for the tier that is currently most constrained, so you can track your budget without parsing bodies:

| Header                | Meaning                                                              |
| --------------------- | -------------------------------------------------------------------- |
| `RateLimit-Limit`     | Total requests allowed in the current 1-minute window for this tier. |
| `RateLimit-Remaining` | How many requests you can still make before being throttled.         |
| `RateLimit-Reset`     | Seconds until the current window resets.                             |

```http theme={null}
HTTP/1.1 200 OK
Content-Type: application/json
RateLimit-Limit: 300
RateLimit-Remaining: 214
RateLimit-Reset: 42
```

Inspect these on every response and slow down proactively when `RateLimit-Remaining` gets low — it is always cheaper than recovering from a `429`.

## What a 429 looks like

When any tier is exceeded, the API responds with `429 Too Many Requests`. Back off for at least `RateLimit-Reset` seconds before retrying.

```http theme={null}
HTTP/1.1 429 Too Many Requests
RateLimit-Limit: 300
RateLimit-Remaining: 0
RateLimit-Reset: 37
```

## Handling throttling

A few patterns work well in practice:

1. **Watch the headers, not the errors.** Adjust your request cadence based on `RateLimit-Remaining` rather than waiting for a `429`.
2. **Back off exponentially on retry.** If you do get throttled, wait at least `RateLimit-Reset` seconds before retrying, then double the wait on each consecutive failure.
3. **Re-use JWTs.** Call `/v2/auth` at most once per token lifetime (\~1 hour). Hammering the auth endpoint wastes your Tier 1 budget and does nothing for your Tier 3 budget.
4. **Fix errors fast.** If you hit Tier 2, it means something in your client is spamming invalid requests. Fix the root cause — retries against a broken request only burn your IP budget.
5. **Batch where possible.** List endpoints support pagination with `limit` up to 200 for most resources — one larger list call is always cheaper than many small ones against your Tier 3 budget.
6. **Avoid tight polling loops.** Until [webhooks](/webhooks) ship, polling is sometimes unavoidable — but keep intervals reasonable (seconds, not milliseconds) and use `date[0]` / `date[1]` or sort filters to fetch only what changed.
7. **Use a single integrator per workload.** Splitting traffic across many integrators to multiply the quota is a policy violation; Clopos monitors for it.

## Need a higher limit?

If 300 requests per minute is not enough for a legitimate use case (for example, a large delivery marketplace or a migration batch job), contact Clopos support at [dev@clopos.com](mailto:dev@clopos.com) with your `integrator_id`, the brand(s) involved, and a description of the workload. Quotas are adjusted on a per-tenant basis.