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

# Rate limits

> Per-token limits surfaced via X-RateLimit headers.

export const Def = ({term, type, defaultValue, required, children}) => <>
    <dt className="gv-def-list__term">
      <span className="gv-def-list__name">{term}</span>
      {type && <span className="gv-def-list__type">{type}</span>}
      {required && <span className="gv-def-list__required">required</span>}
      {defaultValue !== undefined && <span className="gv-def-list__default">
          default <code>{defaultValue}</code>
        </span>}
    </dt>
    <dd className="gv-def-list__description">{children}</dd>
  </>;

export const DefList = ({children}) => <dl className="gv-def-list">{children}</dl>;

export const Eyebrow = ({label, tone = "default"}) => <div className={`gv-eyebrow gv-eyebrow--${tone}`}>
    <span className="gv-eyebrow__bar" aria-hidden="true" />
    <span className="gv-eyebrow__label">{label}</span>
  </div>;

<Eyebrow label="LIMITS" />

Rate limits are enforced per-token. Every response carries headers telling you the current ceiling, how much of it remains, and when the counter resets. Reading those headers is the most reliable way to stay under the limit. By the end of this page you will know what the headers carry, what a 429 looks like, and how to back off when you hit one.

## Response headers

<DefList>
  <Def term="X-RateLimit-Limit" type="integer">Maximum requests allowed in the current window for this token.</Def>
  <Def term="X-RateLimit-Remaining" type="integer">How many requests remain in the current window.</Def>
  <Def term="X-RateLimit-Reset" type="integer">Unix timestamp (seconds) when the window expires and the counter resets.</Def>
</DefList>

<Note>
  Exact numeric limits are not published. If your integration needs a higher ceiling, contact support with traffic estimates.
</Note>

## When you hit the limit

The API returns `429 Too Many Requests` with a `Retry-After` header carrying the wait in seconds:

```json theme={null}
{
  "error": {
    "code":    "rate_limited",
    "message": "Rate limit exceeded for this token",
    "details": {
      "retry_after_seconds": 14
    }
  }
}
```

The `Retry-After` value is set as both the response header and `details.retry_after_seconds`. They will match.

## Limit categories

Not every endpoint counts against the same bucket. The platform splits traffic across a small number of categories so a chatty log tail does not steal capacity from a publish, and a high-volume capability call does not throttle out a token rotation. Categories share the same response headers — the `X-RateLimit-*` values you see reflect the bucket the *current* request was checked against.

<DefList>
  <Def term="reads">
    Cursor-paginated list endpoints and single-resource fetches. Generous ceiling; tuned for batch read patterns.
  </Def>

  <Def term="writes">
    Mutating operations on resources — patches, publishes, mint, rotate. Lower ceiling than reads.
  </Def>

  <Def term="auth">
    Sign-in, token mint, password reset, MFA challenge. Stricter ceiling, with a separate per-account strike counter on failed attempts that can lock an account independently of the per-token rate limit.
  </Def>

  <Def term="streaming">
    Long-lived endpoints (log tail, agent surface). Counted by connection-seconds rather than request count; bucket header values reflect remaining connection time on those endpoints.
  </Def>
</DefList>

A token is held to the lowest remaining ceiling across whichever bucket the current request touches. There is no aggregate "total requests per minute" — each bucket is independent.

## How to back off

<DefList>
  <Def term="Wait Retry-After exactly">Do not retry immediately. The server is telling you the precise wait.</Def>
  <Def term="Backoff on persistent 429">If retries keep hitting the limit, start at `Retry-After`, then double the interval each subsequent attempt, with jitter.</Def>
  <Def term="Smooth bursty work">Queue bursts rather than firing them in parallel — even, paced dispatch respects the window.</Def>
  <Def term="Per-token isolation">Mint separate keys for separate integrations. One noisy workload cannot exhaust headroom for another.</Def>
</DefList>

## Next

<Card title="Idempotency" icon="rotate" href="/api-reference/idempotency">
  Make write retries safe even when the response was already produced.
</Card>