Pieprasījumu biežuma limiti un kvotas

Divu veidu limiti nodrošina, ka API darbojas ātri visiem:

• Atslēgas pieprasījumu biežuma limits: cik pieprasījumu sekundē tā drīkst sūtīt, un īslaicīgs pīķis, kas pieļauj īsus slodzes kāpumus.
• Organizācijas kvotas: cik pieprasījumu visas tās atslēgas kopā drīkst nosūtīt minūtē, dienā un mēnesī.

Abi ir atkarīgi no organizācijas plāna. Katra atbilde parāda jūsu pašreizējo stāvokli, tāpēc pareizi veidotam klientam nekas nav jāmin.

Atslēgas pieprasījumu biežuma limits

Katrai atslēgai ir pastāvīgs ātrums un īslaicīgs pīķis. Īslaicīgais pīķis ļauj uzreiz nosūtīt tik daudz pieprasījumu; pēc tam pieprasījumi tiek atļauti pastāvīgajā ātrumā.

Klasi nosaka organizācijas plāns. GET /v1/me parāda tās atslēgas klasi, ātrumu un īslaicīgo pīķi, ar kuru operācija izsaukta (rate_limit). Limits attiecas uz atslēgu kopumā neatkarīgi no tā, cik API serveru apkalpo jūsu pieprasījumus.

Straumēšanas operācijas – POST /v1/chat (ar "stream": true vai bez tā) un GET /v1/jobs/stream – ir ārpus atslēgas pieprasījumu biežuma limita: tās to neizlieto, un to galvenēs RateLimit nav elementa "key". Tās tiek ieskaitītas organizācijas kvotās, katra vienreiz, kad pieprasījums sākas. Jautājumiem ir savi limiti, kas aprakstīti tālāk.

Organizācijas kvotas

Plāns var noteikt organizācijai pieprasījumu kvotas: minūtē, dienā un mēnesī. Laika logi ir kalendāra periodi UTC laikā: minūte sākas :00 sekundēs, diena – 00:00 UTC, mēnesis – pirmajā dienā 00:00 UTC. Tiek ieskaitīts katrs pieprasījums ar organizācijas atslēgu vai OAuth marķieri jebkurā adresē. Straumēšanas pieprasījums tiek ieskaitīts vienreiz, kad tas sākas, lai cik ilgi tas turpinātos; ja kvota ir izlietota, tas tiek atteikts ar 429 tāpat kā jebkurš cits pieprasījums. Pieprasījums, kas atteikts ar 429, netiek ieskaitīts.

Galvenes

Katrā atbildē uz pieprasījumu ar atslēgu ir norādīti limiti, kas uz to attiecas:

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 un RateLimit atbilst IETF melnrakstam RateLimit header fields for HTTP. Katrs elements ir viens limits:

X-RateLimit-Limit, X-RateLimit-Remaining un X-RateLimit-Reset vienkāršākā formā parāda stingrāko no šiem limitiem klientiem, kas rakstīti pirms RateLimit ieviešanas. X-RateLimit-Reset ir sekundēs.

Kad limits ir sasniegts

API atbild ar 429 Too Many Requests un galveni Retry-After sekundēs:

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

Nogaidiet Retry-After norādīto laiku un atkārtojiet pieprasījumu. POST un PATCH atkārtojiet ar to pašu Idempotency-Key. Atkārtošanas palīgfunkcijas ceļvedī Kļūdas dara abus.

Arī citi plāna limiti atbild ar 429 un Retry-After, piemēram, jautājumu skaits dienā (limits.questions) vai vienlaikus sagatavojamo atbilžu skaits (limits.concurrent_answers). Apstrādājiet tos tāpat.

Kā palikt limitu robežās

• Lasiet RateLimit un palēniniet tempu, kad r kļūst mazs, nevis gaidiet 429.
• Sadaliet lielapjoma darbu laikā un izmantojiet partiju operācijas, kur tās ir: viena 100 dokumentu partija ir viens pieprasījums.
• Neaptaujājiet izmaiņas ciešā ciklā. Abonējiet webhook paziņojumus vai lasiet notikumu plūsmu ik pēc dažām sekundēm.
• Paralēlus apstrādes procesus darbiniet ar kopīgu ierobežotāju. Vairāki procesi ar vienu atslēgu dala vienu pieprasījumu biežuma limitu.
• Ja jūsu integrācijai vajag vairāk, jautājiet savai kontaktpersonai Sursā par augstāku klasi.