Limity frekvencie a kvóty

API udržiavajú rýchle pre všetkých dva druhy limitov:

• Limit frekvencie kľúča: koľko požiadaviek za sekundu smie posielať, s nárazovou špičkou pre krátke vrcholy.
• Kvóty organizácie: koľko požiadaviek smú všetky jej kľúče spolu poslať za minútu, za deň a za mesiac.

Oba závisia od tarify organizácie. Každá odpoveď vám povie, ako na tom ste, takže dobre napísaný klient nikdy nemusí hádať.

Limit frekvencie kľúča

Každý kľúč dostane stálu frekvenciu a nárazovú špičku. Špička vám umožní poslať naraz toľko požiadaviek; potom sa požiadavky povoľujú stálou frekvenciou.

Trieda vyplýva z tarify organizácie. GET /v1/me ukazuje triedu, frekvenciu a špičku kľúča, ktorý ho volá (rate_limit). Limit platí pre kľúč ako celok bez ohľadu na to, koľko serverov API obsluhuje vaše požiadavky.

Streamovacie operácie POST /v1/chat (s "stream": true aj bez neho) a GET /v1/jobs/stream sú mimo limitu frekvencie kľúča: nečerpajú ho a ich hlavičky RateLimit nemajú položku "key". Do kvót organizácie sa však započítajú, každá raz, keď sa požiadavka začne. Otázky majú vlastné limity, opísané nižšie.

Kvóty organizácie

Tarifa môže organizácii nastaviť kvóty požiadaviek: za minútu, za deň a za mesiac. Okná sú kalendárne obdobia v UTC: minúta začína v sekunde :00, deň o 00:00 UTC, mesiac prvý deň o 00:00 UTC. Započíta sa každá požiadavka s kľúčom alebo tokenom OAuth organizácie, na ktorejkoľvek adrese. Streamovacia požiadavka sa započíta raz, keď sa začne, bez ohľadu na to, ako dlho trvá; pri vyčerpanej kvóte sa odmietne s 429 ako každá iná požiadavka. Požiadavka odmietnutá s 429 sa nezapočíta.

Hlavičky

Každá odpoveď na požiadavku s kľúčom nesie limity, ktoré sa na ňu vzťahujú:

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 zodpovedajú návrhu IETF RateLimit header fields for HTTP. Každá položka je jeden limit:

X-RateLimit-Limit, X-RateLimit-Remaining a X-RateLimit-Reset uvádzajú najprísnejší z týchto limitov v jednoduchšej podobe pre klientov napísaných pred zavedením RateLimit. X-RateLimit-Reset je v sekundách.

Keď sa dosiahne limit

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

{
  "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čkajte podľa Retry-After a požiadavku zopakujte. POST a PATCH opakujte s rovnakým Idempotency-Key. Pomocné funkcie na opakovanie v návode Chyby robia oboje.

Aj ďalšie limity tarify odpovedajú 429 s Retry-After, napríklad počet otázok za deň (limits.questions) alebo počet odpovedí, ktoré sa pripravujú súčasne (limits.concurrent_answers). Spracujte ich rovnako.

Ako zostať pod limitmi

• Čítajte RateLimit a spomaľte, keď r klesá, namiesto toho, aby ste čakali na 429.
• Hromadnú prácu rozložte v čase a tam, kde existujú, používajte dávkové operácie: jedna dávka 100 dokumentov je jedna požiadavka.
• Nezisťujte zmeny v rýchlej slučke dopytovania. Prihláste sa na odber webhookov alebo čítajte kanál udalostí raz za niekoľko sekúnd.
• Paralelné procesy spúšťajte so spoločným obmedzovačom frekvencie. Viacero procesov s jedným kľúčom zdieľa jeden limit frekvencie.
• Ak vaša integrácia potrebuje viac, opýtajte sa svojej kontaktnej osoby v Surse na vyššiu triedu.