Sageduspiirangud ja kvoodid

Kahte liiki piirangud hoiavad API kõigi jaoks kiirena:

• Võtme sageduspiirang: mitu päringut sekundis võib võti saata, koos tipuvaruga lühikeste tippude jaoks.
• Organisatsiooni kvoodid: mitu päringut võivad kõik selle võtmed kokku saata minutis, päevas ja kuus.

Mõlemad sõltuvad organisatsiooni paketist. Iga vastus näitab teie praegust seisu, seega ei pea korrektselt käituv klient kunagi oletama.

Võtme sageduspiirang

Iga võti saab püsiva kiiruse ja tipuvaru. Tipuvaru lubab saata korraga nii palju päringuid; pärast seda lubatakse päringuid püsiva kiirusega.

Klass tuleb organisatsiooni paketist. GET /v1/me näitab seda kutsuva võtme klassi, kiirust ja tipuvaru (rate_limit). Piirang kehtib võtmele tervikuna, olenemata sellest, mitu API-serverit teie päringuid teenindab.

Voogedastuse lõpp-punktid POST /v1/chat (väärtusega "stream": true või ilma) ja GET /v1/jobs/stream jäävad võtme sageduspiirangust välja: need ei kuluta seda ja nende päistes RateLimit ei ole elementi "key". Organisatsiooni kvootide hulka loetakse need siiski: iga päring üks kord, selle alguses. Küsimustel on omad piirangud, mida kirjeldatakse allpool.

Organisatsiooni kvoodid

Pakett võib määrata organisatsioonile päringukvoodid: minutis, päevas ja kuus. Ajaaknad on kalendriperioodid UTC järgi: minut algab sekundil :00, päev kell 00:00 UTC, kuu esimesel päeval kell 00:00 UTC. Arvesse läheb iga organisatsiooni võtme või OAuth-loaga tehtud päring mis tahes aadressil. Voogedastuspäring loetakse üks kord, selle alguses, olenemata sellest, kui kaua see kestab; kui kvoot on täis, lükatakse see nagu iga teine päring tagasi vastusega 429. Vastusega 429 tagasi lükatud päringut arvesse ei võeta.

Päised

Iga vastus võtmega tehtud päringule sisaldab sellele kehtivaid piiranguid:

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 ja RateLimit järgivad IETF-i kavandit RateLimit header fields for HTTP. Iga element on üks piirang:

X-RateLimit-Limit, X-RateLimit-Remaining ja X-RateLimit-Reset näitavad neist piirangutest rangeimat lihtsamal kujul klientidele, mis kirjutati enne päise RateLimit tekkimist. X-RateLimit-Reset on sekundites.

Kui piirang on täis

API vastab 429 Too Many Requests päisega Retry-After, mille väärtus on sekundites:

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

Oodake päises Retry-After antud aeg ära ja korrake päringut. Korrake päringuid POST ja PATCH sama päisega Idempotency-Key. Juhendi Vead korduskatsete abifunktsioonid teevad mõlemat.

Ka teised paketi piirangud vastavad 429 päisega Retry-After, näiteks küsimuste arv päevas (limits.questions) või samal ajal koostatavate vastuste arv (limits.concurrent_answers). Käsitlege neid samamoodi.

Piirangute piires püsimine

• Lugege päist RateLimit ja aeglustage, kui r läheb väikeseks, selle asemel et oodata vastust 429.
• Jaotage hulgitöö ajas ja kasutage partiilõpp-punkte, kus need on olemas: üks 100 dokumendiga partii on üks päring.
• Ärge küsitlege muudatusi tihedas tsüklis. Tellige veebihaagid või lugege sündmuste linti iga paari sekundi järel.
• Käivitage paralleelsed töötlusprotsessid ühise sageduspiirajaga. Mitu sama võtmega protsessi jagavad üht sageduspiirangut.
• Kui teie integratsioon vajab rohkem, küsige oma kontaktisikult Sursas kõrgema klassi kohta.