Hastighetsbegränsningar och kvoter

Två typer av gränser håller API:et snabbt för alla:

• En nyckels hastighetsbegränsning: hur många anrop per sekund den får skicka, med en topp (burst) för kortvariga anhopningar av anrop.
• Organisationens kvoter: hur många anrop alla dess nycklar tillsammans får skicka per minut, per dag och per månad.

Båda beror på organisationens prisplan. Varje svar visar var du står, så en klient som sköter sig behöver aldrig gissa.

En nyckels hastighetsbegränsning

Varje nyckel får en jämn takt och en topp. Toppen låter dig skicka så många anrop på en gång; därefter tillåts anrop i den jämna takten.

Klassen kommer från organisationens prisplan. GET /v1/me visar klass, takt och topp för nyckeln som anropar den (rate_limit). Gränsen gäller för nyckeln som helhet, oavsett hur många API-servrar som betjänar dina anrop.

De strömmande slutpunkterna, POST /v1/chat (med eller utan "stream": true) och GET /v1/jobs/stream, ligger utanför nyckelns hastighetsbegränsning: de förbrukar den inte, och deras RateLimit-huvuden har ingen post "key". De räknas däremot mot organisationens kvoter, en gång var, när anropet startar. Frågor har egna gränser, som beskrivs nedan.

Organisationens kvoter

En prisplan kan ange kvoter för organisationens anrop: per minut, per dag och per månad. Fönstren är kalenderperioder i UTC: en minut börjar vid :00 sekunder, en dag kl. 00:00 UTC, en månad den första dagen kl. 00:00 UTC. Varje anrop med en av organisationens nycklar eller OAuth-token räknas, på vilken adress som helst. Ett strömmande anrop räknas en gång, när det startar, oavsett hur länge det pågår; när en kvot är förbrukad avvisas det med 429 som alla andra anrop. Ett anrop som avvisas med 429 räknas inte.

Huvudena

Varje svar på ett anrop med en nyckel innehåller de gränser som gäller för det:

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 och RateLimit följer IETF-utkastet RateLimit header fields for HTTP. Varje post är en gräns:

X-RateLimit-Limit, X-RateLimit-Remaining och X-RateLimit-Reset rapporterar den striktaste av de här gränserna i en enklare form, för klienter som skrevs innan RateLimit fanns. X-RateLimit-Reset anges i sekunder.

När en gräns nås

API:et svarar 429 Too Many Requests med huvudet Retry-After i sekunder:

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

Vänta i Retry-After sekunder och upprepa anropet. Upprepa POST och PATCH med samma Idempotency-Key. Hjälpfunktionerna för nya försök i Fel gör båda delarna.

Andra gränser i prisplanen svarar också 429 med Retry-After, till exempel antalet frågor per dag (limits.questions) eller antalet svar som pågår samtidigt (limits.concurrent_answers). Hantera dem på samma sätt.

Håll dig under gränserna

• Läs RateLimit och sakta ned när r blir lågt, i stället för att vänta på en 429.
• Sprid ut massarbete över tid och använd batchslutpunkterna där de finns: en batch med 100 dokument är ett enda anrop.
• Polla inte efter ändringar i en tät loop. Prenumerera på webhookar eller läs händelseflödet med några sekunders mellanrum.
• Kör parallella arbetsprocesser med en gemensam hastighetsbegränsare. Flera processer med samma nyckel delar på en hastighetsbegränsning.
• Fråga din kontaktperson på Sursa om en högre klass om din integration behöver mer.