Ograničenja učestalosti i kvote

Dvije vrste ograničenja održavaju API brzim za sve:

• Ograničenje učestalosti ključa: koliko zahtjeva u sekundi smije slati, uz nalet (burst) za kratke vrhunce.
• Kvote organizacije: koliko zahtjeva svi njezini ključevi zajedno smiju poslati u minuti, danu i mjesecu.

Oboje ovisi o planu organizacije. Svaki vam odgovor kaže gdje se nalazite, pa klijent koji se ispravno ponaša nikada ne mora pogađati.

Ograničenje učestalosti ključa

Svaki ključ dobiva stalnu brzinu i nalet. Nalet vam omogućuje da odjednom pošaljete toliko zahtjeva; nakon toga zahtjevi se propuštaju stalnom brzinom.

Razred proizlazi iz plana organizacije. GET /v1/me prikazuje razred, brzinu i nalet ključa koji ga poziva (rate_limit). Ograničenje vrijedi za ključ u cjelini, bez obzira na to koliko poslužitelja API-ja obrađuje vaše zahtjeve.

Operacije koje odgovaraju tokom, POST /v1/chat (sa "stream": true ili bez njega) i GET /v1/jobs/stream, izvan su ograničenja učestalosti ključa: ne troše ga, a njihova zaglavlja RateLimit nemaju stavku "key". Ipak se ubrajaju u kvote organizacije, svaka jednom, kad zahtjev počne. Pitanja imaju vlastita ograničenja, opisana u nastavku.

Kvote organizacije

Plan može organizaciji postaviti kvote zahtjeva: u minuti, danu i mjesecu. Prozori su kalendarska razdoblja u UTC-u: minuta počinje u :00 sekundi, dan u 00:00 UTC, mjesec prvog dana u 00:00 UTC. Ubraja se svaki zahtjev s ključem ili OAuth tokenom organizacije, na bilo kojoj adresi. Zahtjev s tokom ubraja se jednom, kad počne, bez obzira na to koliko traje; kad je kvota potrošena, odbija se s 429 kao i svaki drugi zahtjev. Zahtjev odbijen s 429 ne ubraja se.

Zaglavlja

Svaki odgovor na zahtjev s ključem nosi ograničenja koja se na njega primjenjuju:

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 i RateLimit slijede IETF-ov nacrt RateLimit header fields for HTTP. Svaka stavka je jedno ograničenje:

X-RateLimit-Limit, X-RateLimit-Remaining i X-RateLimit-Reset u jednostavnijem obliku izvješćuju o najstrožem od tih ograničenja, za klijente napisane prije nego što je RateLimit postojao. X-RateLimit-Reset izražen je u sekundama.

Kad se dosegne ograničenje

API odgovara s 429 Too Many Requests i zaglavljem Retry-After u sekundama:

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

Pričekajte koliko navodi Retry-After i ponovite zahtjev. POST i PATCH ponovite s istim Idempotency-Key. Pomoćne funkcije za ponovne pokušaje iz vodiča Pogreške rade oboje.

I druga ograničenja plana odgovaraju s 429 i zaglavljem Retry-After, na primjer broj pitanja dnevno (limits.questions) ili broj odgovora koji se istodobno pripremaju (limits.concurrent_answers). Obradite ih na isti način.

Kako ostati unutar ograničenja

• Čitajte RateLimit i usporite kad r postane nizak, umjesto da čekate 429.
• Skupne poslove rasporedite kroz vrijeme i koristite operacije za pakete ondje gdje postoje: jedan paket od 100 dokumenata jedan je zahtjev.
• Ne provjeravajte promjene u uskoj petlji. Pretplatite se na webhookove ili čitajte feed događaja svakih nekoliko sekundi.
• Paralelne radne procese pokrećite sa zajedničkim ograničivačem učestalosti. Više procesa s jednim ključem dijeli jedno ograničenje učestalosti.
• Ako vaša integracija treba više, pitajte svoju kontaktnu osobu u Sursi za viši razred.