Gyakorisági korlátok és kvóták

Kétféle korlát tartja gyorsnak az API-t mindenki számára:

A kulcs gyakorisági korlátja: hány kérést küldhet másodpercenként, a rövid csúcsokhoz csúcskerettel.
A szervezet kvótái: az összes kulcsa együtt hány kérést küldhet percenként, naponta és havonta.

Mindkettő a szervezet csomagjától függ. Minden válasz megmutatja, hol tartasz, így egy jól megírt kliensnek soha nem kell találgatnia.

A kulcs gyakorisági korlátja

Minden kulcs állandó sebességet és csúcskeretet kap. A csúcskeret szerinti számú kérést egyszerre is elküldheted; ezután a kérések az állandó sebességgel engedélyezettek.

Osztály	Sebesség	Csúcskeret
`basic`	5 kérés másodpercenként	25
`standard`	20 kérés másodpercenként	100
`high`	50 kérés másodpercenként	250

Az osztály a szervezet csomagjából adódik. A GET /v1/me megmutatja az őt hívó kulcs osztályát, sebességét és csúcskeretét (rate_limit). A korlát a kulcs egészére érvényes, akárhány API-szerver szolgálja is ki a kéréseidet.

Az adatfolyamot küldő végpontok, a POST /v1/chat ("stream": true értékkel vagy anélkül) és a GET /v1/jobs/stream, kívül esnek a kulcs gyakorisági korlátján: nem fogyasztják, és a RateLimit fejléceikben nincs "key" elem. A szervezet kvótáiba viszont beszámítanak, mindegyik egyszer, a kérés indulásakor. A kérdéseknek saját korlátjaik vannak, ezeket lent ismertetjük.

A szervezet kvótái

A csomag kéréskvótákat állíthat be a szervezetnek: percenként, naponta és havonta. Az időablakok UTC szerinti naptári időszakok: a perc :00 másodperckor kezdődik, a nap 00:00 UTC-kor, a hónap az első napon 00:00 UTC-kor. A szervezet bármely kulcsával vagy OAuth-tokenjével küldött minden kérés beszámít, bármelyik címen. Az adatfolyamot küldő kérés egyszer számít, az indulásakor, akármeddig tart is; ha a kvóta elfogyott, a Sursa 429 válasszal utasítja el, mint bármely más kérést. A 429 válasszal elutasított kérés nem számít bele.

A fejlécek

Minden kulccsal küldött kérésre adott válasz tartalmazza a rá vonatkozó korlátokat:

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

A RateLimit-Policy és a RateLimit fejléc az IETF RateLimit header fields for HTTP tervezetét követi. Minden elem egy korlát:

Elem	Jelentése
`"key"`	A kulcs gyakorisági korlátja. A `q` a csúcskeret, a `w` azoknak a másodperceknek a száma, amelyek alatt az elhasznált csúcskeret újratöltődik.
`"minute"`, `"day"`, `"month"`	A szervezet egy kvótája, ha a csomagban van ilyen. A `q` a kvóta, a `w` az időablak másodpercben.
`r` (a `RateLimit` fejlécben)	Hány kérés maradt még ezen a korláton belül.
`t` (a `RateLimit` fejlécben)	Hány másodperc múlva áll helyre ez a korlát.

Az X-RateLimit-Limit, az X-RateLimit-Remaining és az X-RateLimit-Reset ezek közül a legszigorúbb korlátot jelzi egyszerűbb formában, a RateLimit megjelenése előtt írt kliensek számára. Az X-RateLimit-Reset értéke másodpercben értendő.

Ha elérted a korlátot

Az API 429 Too Many Requests választ ad, másodpercben megadott Retry-After fejléccel:

Kód	Jelentése
`api.rate_limited`	A kulcs gyorsabban küldte a kéréseket, mint amit a sebessége megenged. A `Retry-After` általában egy-két másodperc.
`api.quota_exceeded`	Elfogyott a szervezet egyik kvótája. A `details` megmondja, melyik, és mikor áll vissza.

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

Várd ki a Retry-After idejét, és ismételd meg a kérést. A POST és a PATCH kérést ugyanazzal az Idempotency-Key értékkel ismételd meg. A Hibák útmutató újrapróbálkozó segédfüggvényei mindkettőt elvégzik.

A csomag más korlátai is 429 választ adnak Retry-After fejléccel, például a napi kérdések száma (limits.questions) vagy az egyszerre folyamatban lévő válaszok száma (limits.concurrent_answers). Ezeket ugyanígy kezeld.

Hogyan maradj a korlátokon belül

Olvasd a RateLimit fejlécet, és lassíts, ha az r értéke alacsonyra csökken, ahelyett, hogy megvárnád a 429 választ.
A tömeges munkát oszd el időben, és használd a kötegelt végpontokat, ahol vannak: egy 100 dokumentumos köteg egyetlen kérés.
Ne kérdezd le a változásokat szoros ciklusban. Iratkozz fel webhookokra, vagy néhány másodpercenként olvasd az eseménycsatornát.
A párhuzamos feldolgozókat közös gyakoriságkorlátozóval futtasd. Az egy kulcsot használó folyamatok egy közös gyakorisági korlátot osztanak meg.
Ha az integrációdnak többre van szüksége, kérdezd a kapcsolattartódat a Sursánál magasabb osztályról.