Rate limits and quotas

Two kinds of limits keep the API fast for everyone:

• The rate limit of a key: how many requests per second it may send, with a burst for short peaks.
• The quotas of the organization: how many requests all of its keys together may send per minute, per day and per month.

Both depend on the organization's plan. Every response tells you where you stand, so a well-behaved client never needs to guess.

Rate limit of a key

Each key gets a steady rate and a burst. The burst lets you send that many requests at once; after that, requests are allowed at the steady rate.

The class comes from the organization's plan. GET /v1/me shows the class, rate and burst of the key that calls it (rate_limit). The limit holds for the key as a whole, however many API servers serve your requests.

The streaming endpoints, POST /v1/chat (with or without "stream": true) and GET /v1/jobs/stream, are outside the rate limit of the key: they do not use it up, and their RateLimit headers have no "key" item. They do count toward the quotas of the organization, once each, when the request starts. Questions have limits of their own, described below.

Quotas of the organization

A plan can set request quotas for the organization: per minute, per day and per month. The windows are calendar periods in UTC: a minute starts at :00 seconds, a day at 00:00 UTC, a month on the first day at 00:00 UTC. Every request with a key or an OAuth token of the organization counts, on any address. A streaming request counts once, when it starts, however long it lasts; with a quota used up, it is refused with 429 like any other request. A request refused with 429 does not count.

The headers

Every response to a request with a key carries the limits that apply to it:

RateLimit-Policy: "key";q=100;w=5, "minute";q=1200;w=60, "day";q=200000;w=86400
RateLimit: "key";r=87;t=1, "minute";r=1150;t=23, "day";r=180311;t=40213
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1

RateLimit-Policy and RateLimit follow the IETF draft RateLimit header fields for HTTP. Each item is one limit:

X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset report the strictest of these limits in a simpler form, for clients written before RateLimit existed. X-RateLimit-Reset is in seconds.

When a limit is reached

The API answers 429 Too Many Requests with a Retry-After header in seconds:

{
  "detail": "the organization has used its API request quota for this period",
  "error": {
    "code": "api.quota_exceeded",
    "message": "the organization has used its API request quota for this period",
    "details": {"quota": "day", "limit": 200000, "reset_at": "2026-10-25T00:00:00Z", "retry_after": 40213},
    "request_id": "01JB7…"
  }
}

Wait for Retry-After and repeat the request. Repeat POST and PATCH with the same Idempotency-Key. The retry helpers in Errors do both.

Other limits of the plan also answer 429 with Retry-After, for example the number of questions per day (limits.questions) or answers in progress at the same time (limits.concurrent_answers). Handle them the same way.

Staying under the limits

• Read RateLimit and slow down when r gets low, instead of waiting for a 429.
• Spread bulk work over time, and use the batch endpoints where they exist: one batch of 100 documents is one request.
• Do not poll for changes in a tight loop. Subscribe to webhooks, or read the event feed every few seconds.
• Run parallel workers with a shared limiter. Several processes with one key share one rate limit.
• Ask your Sursa contact about a higher class if your integration needs more.