Limite de frecvență și cote

Două tipuri de limite păstrează API-ul rapid pentru toată lumea:

• Limita de frecvență a unei chei: câte cereri pe secundă poate trimite, cu o rafală pentru vârfurile scurte.
• Cotele organizației: câte cereri pot trimite toate cheile ei împreună pe minut, pe zi și pe lună.

Ambele depind de planul organizației. Fiecare răspuns vă arată unde vă aflați, așa că un client care respectă regulile nu trebuie să ghicească niciodată.

Limita de frecvență a unei chei

Fiecare cheie primește o frecvență constantă și o rafală. Rafala vă permite să trimiteți dintr-odată atâtea cereri; după aceea, cererile sunt permise cu frecvența constantă.

Clasa vine din planul organizației. GET /v1/me arată clasa, frecvența și rafala cheii care îl apelează (rate_limit). Limita se aplică cheii în ansamblu, oricâte servere API ar servi cererile.

Endpointurile cu flux, POST /v1/chat (cu sau fără "stream": true) și GET /v1/jobs/stream, sunt în afara limitei de frecvență a cheii: nu o consumă, iar antetele lor RateLimit nu au elementul "key". Ele se socotesc totuși în cotele organizației, câte o dată fiecare, la începutul cererii. Întrebările au limite proprii, descrise mai jos.

Cotele organizației

Un plan poate stabili cote de cereri pentru organizație: pe minut, pe zi și pe lună. Ferestrele sunt perioade calendaristice în UTC: un minut începe la secunda :00, o zi la 00:00 UTC, o lună în prima zi, la 00:00 UTC. Contează fiecare cerere făcută cu o cheie sau cu un token OAuth al organizației, la orice adresă. O cerere cu flux se socotește o singură dată, la început, oricât ar dura; când o cotă este epuizată, este refuzată cu 429, ca orice altă cerere. O cerere refuzată cu 429 nu se socotește.

Antetele

Fiecare răspuns la o cerere cu cheie poartă limitele care i se aplică:

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 urmează proiectul IETF RateLimit header fields for HTTP. Fiecare element este o limită:

X-RateLimit-Limit, X-RateLimit-Remaining și X-RateLimit-Reset raportează cea mai strictă dintre aceste limite într-o formă mai simplă, pentru clienții scriși înainte să existe RateLimit. X-RateLimit-Reset este în secunde.

Când se atinge o limită

API-ul răspunde 429 Too Many Requests cu un antet Retry-After în secunde:

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

Așteptați cât indică Retry-After și repetați cererea. Repetați POST și PATCH cu același Idempotency-Key. Funcțiile de reîncercare din Erori le fac pe amândouă.

Și alte limite ale planului răspund 429 cu Retry-After, de exemplu numărul de întrebări pe zi (limits.questions) sau răspunsurile aflate în lucru în același timp (limits.concurrent_answers). Tratați-le la fel.

Cum rămâneți sub limite

• Citiți RateLimit și încetiniți când r scade, în loc să așteptați un 429.
• Distribuiți lucrul în volum mare în timp și folosiți endpointurile de loturi acolo unde există: un lot de 100 de documente este o singură cerere.
• Nu interogați modificările într-o buclă strânsă. Abonați-vă la webhookuri sau citiți fluxul de evenimente la câteva secunde.
• Rulați procesele de lucru paralele cu un limitator comun. Mai multe procese cu aceeași cheie au o singură limită de frecvență.
• Întrebați persoana de contact de la Sursa despre o clasă superioară, dacă integrarea are nevoie de mai mult.