Užklausų dažnio limitai ir kvotos

Dvi limitų rūšys užtikrina, kad API visiems veiktų greitai:

• Rakto užklausų dažnio limitas: kiek užklausų per sekundę jis gali siųsti, su pliūpsniu trumpiems pikams.
• Organizacijos kvotos: kiek užklausų visi jos raktai kartu gali išsiųsti per minutę, per dieną ir per mėnesį.

Abu priklauso nuo organizacijos plano. Kiekvienas atsakas praneša, kokia padėtis, todėl tvarkingai veikiančiam klientui niekada nereikia spėlioti.

Rakto užklausų dažnio limitas

Kiekvienas raktas gauna pastovų dažnį ir pliūpsnį. Pliūpsnis leidžia iš karto išsiųsti tiek užklausų; po to užklausos leidžiamos pastoviu dažniu.

Klasę lemia organizacijos planas. GET /v1/me parodo ją kviečiančio rakto klasę, dažnį ir pliūpsnį (rate_limit). Limitas galioja visam raktui, kad ir kiek API serverių aptarnautų jūsų užklausas.

Srautinės operacijos POST /v1/chat (su "stream": true arba be jo) ir GET /v1/jobs/stream nepatenka į rakto užklausų dažnio limitą: jo neišnaudoja, o jų RateLimit antraštėse nėra elemento "key". Į organizacijos kvotas jos įskaičiuojamos – kiekviena vieną kartą, kai užklausa prasideda. Klausimai turi savo limitus, aprašytus toliau.

Organizacijos kvotos

Planas gali nustatyti organizacijai užklausų kvotas: per minutę, per dieną ir per mėnesį. Laiko langai yra kalendoriniai laikotarpiai UTC: minutė prasideda nuo :00 sekundės, diena – 00:00 UTC, mėnuo – pirmąją mėnesio dieną 00:00 UTC. Įskaičiuojama kiekviena užklausa su organizacijos raktu arba OAuth žetonu, bet kuriuo adresu. Srautinė užklausa įskaičiuojama vieną kartą, kai prasideda, kad ir kiek ji truktų; išnaudojus kvotą, ji atmetama su 429, kaip ir bet kuri kita užklausa. Su 429 atmesta užklausa neįskaičiuojama.

Antraštės

Kiekviename atsake į užklausą su raktu nurodomi jai taikomi limitai:

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 ir RateLimit atitinka IETF juodraštį RateLimit header fields for HTTP. Kiekvienas elementas – vienas limitas:

X-RateLimit-Limit, X-RateLimit-Remaining ir X-RateLimit-Reset paprastesne forma praneša griežčiausią iš šių limitų – klientams, parašytiems dar iki RateLimit atsiradimo. X-RateLimit-Reset nurodomas sekundėmis.

Kai limitas pasiekiamas

API grąžina 429 Too Many Requests su antrašte Retry-After sekundėmis:

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

Palaukite Retry-After nurodytą laiką ir pakartokite užklausą. POST ir PATCH kartokite su tuo pačiu Idempotency-Key. Pakartojimų pagalbinės funkcijos iš Klaidos daro ir viena, ir kita.

Kiti plano limitai taip pat grąžina 429 su Retry-After, pavyzdžiui, klausimų skaičius per dieną (limits.questions) arba vienu metu rengiami atsakymai (limits.concurrent_answers). Apdorokite juos taip pat.

Kaip neviršyti limitų

• Skaitykite RateLimit ir sulėtinkite tempą, kai r tampa mažas, – nelaukite 429.
• Masinius darbus paskirstykite laike ir, kur yra, naudokite partijų operacijas: viena 100 dokumentų partija – viena užklausa.
• Pakeitimų netikrinkite tankiu ciklu. Prenumeruokite webhook pranešimus arba kas kelias sekundes skaitykite įvykių juostą.
• Lygiagrečius darbo procesus paleiskite su bendru ribotuvu. Keli procesai su vienu raktu dalijasi vienu užklausų dažnio limitu.
• Jei jūsų integracijai reikia daugiau, paklauskite savo kontaktinio asmens Sursoje apie aukštesnę klasę.