Limity četnosti a kvóty

API zůstává rychlé pro všechny díky dvěma druhům limitů:

Limit četnosti klíče: kolik požadavků za sekundu smí odeslat, s nárazovou špičkou (burst) pro krátkodobé nárůsty.
Kvóty organizace: kolik požadavků smějí všechny její klíče dohromady odeslat za minutu, za den a za měsíc.

Obojí závisí na tarifu organizace. Každá odpověď vám sdělí, jak na tom jste, takže správně napsaný klient nikdy nemusí hádat.

Limit četnosti klíče

Každý klíč má ustálenou četnost a nárazovou špičku. Nárazová špička udává, kolik požadavků lze odeslat najednou; poté jsou požadavky povoleny ustálenou četností.

Třída	Četnost	Nárazová špička
`basic`	5 požadavků za sekundu	25
`standard`	20 požadavků za sekundu	100
`high`	50 požadavků za sekundu	250

Třída vyplývá z tarifu organizace. GET /v1/me ukazuje třídu, četnost a nárazovou špičku klíče, který operaci volá (rate_limit). Limit platí pro klíč jako celek bez ohledu na to, kolik serverů API vaše požadavky obsluhuje.

Streamovací operace POST /v1/chat (s "stream": true i bez něj) a GET /v1/jobs/stream stojí mimo limit četnosti klíče: nečerpají ho a jejich hlavičky RateLimit nemají položku "key". Do kvót organizace se ale započítávají, každá jednou, při zahájení požadavku. Otázky mají vlastní limity, popsané níže.

Kvóty organizace

Tarif může organizaci nastavit kvóty požadavků: za minutu, za den a za měsíc. Okna jsou kalendářní období v UTC: minuta začíná v :00 sekund, den v 00:00 UTC, měsíc prvního dne v 00:00 UTC. Započítává se každý požadavek s klíčem nebo tokenem OAuth organizace, na jakékoli adrese. Streamovací požadavek se započítá jednou, při svém zahájení, ať trvá jakkoli dlouho; při vyčerpané kvótě se odmítne s 429 jako kterýkoli jiný požadavek. Požadavek odmítnutý s 429 se nezapočítává.

Hlavičky

Každá odpověď na požadavek s klíčem nese limity, které se na něj vztahují:

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 a RateLimit se řídí návrhem IETF RateLimit header fields for HTTP. Každá položka představuje jeden limit:

Položka	Význam
`"key"`	Limit četnosti klíče. `q` je nárazová špička, `w` počet sekund, za které se vyčerpaná nárazová špička obnoví.
`"minute"`, `"day"`, `"month"`	Kvóta organizace, pokud ji tarif má. `q` je kvóta, `w` okno v sekundách.
`r` (v `RateLimit`)	Kolik požadavků v rámci tohoto limitu zbývá.
`t` (v `RateLimit`)	Počet sekund do obnovení tohoto limitu.

X-RateLimit-Limit, X-RateLimit-Remaining a X-RateLimit-Reset hlásí nejpřísnější z těchto limitů v jednodušší podobě pro klienty napsané dřív, než hlavička RateLimit existovala. X-RateLimit-Reset je v sekundách.

Po dosažení limitu

API odpoví 429 Too Many Requests s hlavičkou Retry-After v sekundách:

Kód	Význam
`api.rate_limited`	Klíč odesílal požadavky rychleji, než dovoluje jeho četnost. `Retry-After` bývá sekunda nebo dvě.
`api.quota_exceeded`	Kvóta organizace je vyčerpaná. `details` uvádí, která to je a kdy se obnoví.

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

Počkejte podle Retry-After a požadavek zopakujte. POST a PATCH opakujte se stejným Idempotency-Key. Pomocné funkce pro opakování na stránce Chyby dělají obojí.

Také další limity tarifu odpovídají 429 s Retry-After, například počet otázek za den (limits.questions) nebo počet současně rozpracovaných odpovědí (limits.concurrent_answers). Zacházejte s nimi stejně.

Jak zůstat pod limity

Čtěte RateLimit a zpomalte, jakmile hodnota r klesne nízko; nečekejte na 429.
Hromadnou práci rozložte v čase a tam, kde existují, používejte dávkové operace: jedna dávka 100 dokumentů je jeden požadavek.
Nezjišťujte změny v těsné smyčce. Přihlaste se k odběru webhooků, nebo čtěte kanál událostí každých několik sekund.
Paralelní procesy spouštějte se společným omezovačem četnosti. Několik procesů s jedním klíčem sdílí jeden limit četnosti.
Pokud vaše integrace potřebuje víc, zeptejte se svého kontaktu v Surse na vyšší třídu.