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

# Rate limits

> Per-organization tiers, per-category budgets, standard headers, and how idempotency replay interacts.

Rate limits are applied **per `IntegrationOrganization`**, not per API
client. Your tier is visible via `GET /v1/me` under
`capabilities.rateLimitTier`.

## Tier matrix

| Tier          | Read / min | Write / min | Webhook management / min | Burst      |
| ------------- | ---------: | ----------: | -----------------------: | ---------- |
| `STANDARD`    |        300 |          60 |                       10 | 2× for 10s |
| `HIGH_VOLUME` |       1000 |         200 |                       30 | 2× for 10s |
| `ENTERPRISE`  |    bespoke |     bespoke |                  bespoke | bespoke    |

* **Read** — any `GET`.
* **Write** — `POST`, `PATCH`, `PUT`, `DELETE`.
* **Webhook management** — the `/v1/webhooks` endpoints specifically.

`ENTERPRISE` is assigned by agreement; even enterprise tiers have a hard
absolute ceiling to protect shared infrastructure.

## Response headers

Every response (including 200s) carries rate-limit headers for your
category:

```
X-RateLimit-Limit: 300
X-RateLimit-Remaining: 287
X-RateLimit-Reset: 1729684260
X-RateLimit-Category: read
```

* `X-RateLimit-Limit` — requests allowed in the current window.
* `X-RateLimit-Remaining` — requests still available.
* `X-RateLimit-Reset` — Unix timestamp when the window resets.
* `X-RateLimit-Category` — which bucket this request counted against.

## Rate-limit exceeded → 429

```
HTTP/1.1 429 Too Many Requests
Retry-After: 37
Content-Type: application/problem+json

{
  "type": "https://api.novatrade24.com/problems/rate-limited",
  "title": "Rate Limit Exceeded",
  "status": 429,
  "detail": "60 requests per minute for write category exceeded.",
  "traceId": "req_..."
}
```

Honor `Retry-After`. Exponential back-off **on top of** `Retry-After` is
good defense against stacked bursts, not a replacement.

## Client backoff pattern

```typescript theme={null}
async function callWithBackoff(req: RequestInit, url: string, maxAttempts = 5) {
  for (let attempt = 0; attempt < maxAttempts; attempt++) {
    const r = await fetch(url, req);
    if (r.status !== 429) return r;

    const retryAfter = parseInt(r.headers.get('Retry-After') ?? '1', 10);
    const jitter = Math.random() * 500;
    await new Promise((res) => setTimeout(res, retryAfter * 1000 + jitter));
  }
  throw new Error('Rate limit exceeded after retries');
}
```

## Idempotent replay is free

A repeat request with the same `Idempotency-Key` and body returns the
cached response. **It does not decrement your rate-limit budget.**
Retrying aggressively after a transient network failure is cheap — you
won't exhaust your quota on the retry.

## Webhook deliveries do NOT count

Outbound webhook deliveries are independent of your inbound rate limit.
NT24 sending events to your URL does not reduce your budget for calling
our API.

## Circuit breaker

If we see **10 consecutive `429`s** from a single API client, we auto-pause
that client for 15 minutes and email your organization admin. The pause
is per-client, not per-organization — other clients on the same org keep
working.

Correctly implementing `Retry-After` and jitter prevents you from hitting
the circuit breaker.

## Asking for a higher tier

Reach out via [our contact page](https://www.novatrade24.com/contact)
with:

* Your `organizationUuid`.
* Current tier.
* Expected sustained and peak request rate per category.
* Business justification.

We adjust tier via capability flag — no code change on your side.

## Next

<CardGroup cols={2}>
  <Card title="Error reference" icon="triangle-exclamation" href="/reference/errors">
    Full `429 rate-limited` payload.
  </Card>

  <Card title="Idempotency" icon="arrows-rotate" href="/concepts/idempotency">
    Free retries via `Idempotency-Key`.
  </Card>
</CardGroup>