Ограничења учесталости и квоте

Две врсте ограничења одржавају API брзим за све:

• Ограничење учесталости кључа: колико захтева у секунди кључ сме да шаље, уз налет (burst) за кратке врхове оптерећења.
• Квоте организације: колико захтева сви њени кључеви заједно смеју да пошаљу у минуту, у дану и у месецу.

Обе врсте зависе од плана организације. Сваки одговор вам говори где се налазите, па добро написан клијент никада не мора да нагађа.

Ограничење учесталости кључа

Сваки кључ добија сталну учесталост и налет. Налет вам омогућава да толико захтева пошаљете одједном; после тога захтеви се пропуштају сталном учесталошћу.

Класа потиче из плана организације. GET /v1/me приказује класу, учесталост и налет кључа који га позива (rate_limit). Ограничење важи за кључ у целини, без обзира на то колико API сервера обрађује ваше захтеве.

Операције које шаљу ток, POST /v1/chat (са "stream": true или без њега) и GET /v1/jobs/stream, налазе се ван ограничења учесталости кључа: не троше га, а њихова заглавља RateLimit немају ставку "key". Урачунавају се у квоте организације, свака једном, када захтев почне. Питања имају сопствена ограничења, описана у наставку.

Квоте организације

План може да постави квоте захтева за организацију: по минуту, по дану и по месецу. Прозори су календарски периоди у UTC: минут почиње у :00 секунди, дан у 00:00 UTC, а месец првог дана у 00:00 UTC. Рачуна се сваки захтев са кључем или OAuth токеном организације, на било којој адреси. Захтев који шаље ток рачуна се једном, када почне, без обзира на то колико траје; када је квота потрошена, одбија се са 429 као и сваки други захтев. Захтев одбијен са 429 се не рачуна.

Заглавља

Сваки одговор на захтев са кључем садржи ограничења која се на њега примењују:

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 и RateLimit прате IETF нацрт RateLimit header fields for HTTP. Свака ставка је једно ограничење:

X-RateLimit-Limit, X-RateLimit-Remaining и X-RateLimit-Reset у једноставнијем облику приказују најстроже од ових ограничења, за клијенте написане пре него што је RateLimit постојао. X-RateLimit-Reset је у секундама.

Када је ограничење достигнуто

API одговара са 429 Too Many Requests и заглављем Retry-After у секундама:

{
  "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…"
  }
}

Сачекајте Retry-After и поновите захтев. POST и PATCH понављајте са истим Idempotency-Key. Помоћне функције за поновне покушаје из водича Грешке раде обоје.

Друга ограничења плана такође одговарају са 429 и Retry-After, на пример број питања дневно (limits.questions) или број одговора који се истовремено припремају (limits.concurrent_answers). Обрађујте их на исти начин.

Како да останете испод ограничења

• Читајте RateLimit и успорите када r падне ниско, уместо да чекате 429.
• Масовни посао распоредите кроз време и користите пакетне операције где постоје: један пакет од 100 докумената је један захтев.
• Не проверавајте измене у брзој петљи. Претплатите се на вебхукове или читајте фид догађаја на сваких неколико секунди.
• Паралелне процесе покрећите са заједничким ограничавачем учесталости. Више процеса са једним кључем дели једно ограничење учесталости.
• Ако вашој интеграцији треба више, питајте своју особу за контакт за платформу Sursa о вишој класи.