Nopeusrajoitukset ja kiintiöt

Kahdenlaiset rajat pitävät API:n nopeana kaikille:

• Avaimen nopeusrajoitus: kuinka monta pyyntöä sekunnissa avain saa lähettää, ja purske lyhyitä huippuja varten.
• Organisaation kiintiöt: kuinka monta pyyntöä sen kaikki avaimet yhteensä saavat lähettää minuutissa, päivässä ja kuukaudessa.

Molemmat riippuvat organisaation paketista. Jokainen vastaus kertoo, missä mennään, joten hyvin toteutetun asiakasohjelman ei koskaan tarvitse arvailla.

Avaimen nopeusrajoitus

Jokainen avain saa tasaisen nopeuden ja purskeen. Purskeen verran pyyntöjä voi lähettää kerralla; sen jälkeen pyyntöjä sallitaan tasaisella nopeudella.

Luokka määräytyy organisaation paketin mukaan. GET /v1/me näyttää sitä kutsuvan avaimen luokan, nopeuden ja purskeen (rate_limit). Raja koskee avainta kokonaisuutena riippumatta siitä, kuinka moni API-instanssi palvelee pyyntöjäsi.

Virtana vastaavat päätepisteet, POST /v1/chat ("stream": true -asetuksella tai ilman) ja GET /v1/jobs/stream, ovat avaimen nopeusrajoituksen ulkopuolella: ne eivät kuluta sitä, eikä niiden RateLimit-otsakkeissa ole "key"-kohdetta. Ne lasketaan kuitenkin organisaation kiintiöihin, kukin kerran, kun pyyntö alkaa. Kysymyksillä on omat rajansa, jotka kuvataan alempana.

Organisaation kiintiöt

Paketti voi asettaa organisaatiolle pyyntökiintiöt minuuttia, päivää ja kuukautta kohden. Aikaikkunat ovat kalenterijaksoja UTC-ajassa: minuutti alkaa sekunnista :00, päivä kello 00.00 UTC ja kuukausi kuun ensimmäisenä päivänä kello 00.00 UTC. Jokainen organisaation avaimella tai OAuth-käyttöoikeustunnuksella tehty pyyntö lasketaan, missä osoitteessa tahansa. Virtana vastaava pyyntö lasketaan kerran, kun se alkaa, kesti se kuinka kauan tahansa; kun kiintiö on käytetty, se hylätään 429-vastauksella kuten mikä tahansa muu pyyntö. 429-vastauksella hylättyä pyyntöä ei lasketa.

Otsakkeet

Jokaisessa vastauksessa avaimella tehtyyn pyyntöön kerrotaan sitä koskevat rajat:

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 noudattavat IETF:n luonnosta RateLimit header fields for HTTP. Jokainen kohta on yksi raja:

X-RateLimit-Limit, X-RateLimit-Remaining ja X-RateLimit-Reset kertovat näistä rajoista tiukimman yksinkertaisemmassa muodossa asiakasohjelmille, jotka on kirjoitettu ennen RateLimit-otsakkeen käyttöönottoa. X-RateLimit-Reset on sekunteina.

Kun raja tulee vastaan

API vastaa 429 Too Many Requests ja lähettää Retry-After-otsakkeen sekunteina:

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

Odota Retry-After-otsakkeen ilmoittama aika ja toista pyyntö. Toista POST ja PATCH samalla Idempotency-Key-otsakkeella. Oppaan Virheet uusintayritysfunktiot tekevät molemmat.

Myös paketin muut rajat vastaavat 429 ja Retry-After, esimerkiksi kysymysten määrä päivässä (limits.questions) tai samaan aikaan käynnissä olevat vastaukset (limits.concurrent_answers). Käsittele ne samalla tavalla.

Rajojen alapuolella pysyminen

• Lue RateLimit ja hidasta, kun r pienenee, äläkä odota 429-vastausta.
• Levitä massatyöt pidemmälle ajalle ja käytä eräpäätepisteitä, kun niitä on: yksi 100 asiakirjan erä on yksi pyyntö.
• Älä kysele muutoksia tiiviissä silmukassa. Tilaa webhookit tai lue tapahtumasyötettä muutaman sekunnin välein.
• Aja rinnakkaisia työprosesseja yhteisellä nopeusrajoittimella. Useat prosessit, joilla on sama avain, jakavat yhden nopeusrajoituksen.
• Kysy yhteyshenkilöltäsi Sursassa korkeampaa luokkaa, jos integraatiosi tarvitsee enemmän.