Hastighetsgrenser og kvoter

To typer grenser holder API-et raskt for alle:

• Hastighetsgrensen for en nøkkel: hvor mange forespørsler per sekund den kan sende, med en burst for korte topper.
• Kvotene for organisasjonen: hvor mange forespørsler alle nøklene til organisasjonen til sammen kan sende per minutt, per dag og per måned.

Begge avhenger av organisasjonens prisplan. Hvert svar forteller deg hvor du står, så en klient som oppfører seg riktig, trenger aldri å gjette.

Hastighetsgrensen for en nøkkel

Hver nøkkel får en jevn hastighet og en burst. Burst lar deg sende så mange forespørsler på én gang; deretter tillates forespørsler i den jevne hastigheten.

Klassen kommer fra organisasjonens prisplan. GET /v1/me viser klassen, hastigheten og burst for nøkkelen som kaller den (rate_limit). Grensen gjelder for nøkkelen som helhet, uansett hvor mange API-servere som betjener forespørslene dine.

Operasjonene med strømming, POST /v1/chat (med eller uten "stream": true) og GET /v1/jobs/stream, står utenfor nøkkelens hastighetsgrense: De bruker den ikke opp, og RateLimit-headerne deres har ikke noe "key"-element. De teller derimot mot organisasjonens kvoter, én gang hver, når forespørselen starter. Spørsmål har egne grenser, som er beskrevet nedenfor.

Organisasjonens kvoter

En prisplan kan sette kvoter for organisasjonens forespørsler: per minutt, per dag og per måned. Tidsvinduene er kalenderperioder i UTC: Et minutt begynner ved :00 sekunder, et døgn kl. 00:00 UTC og en måned den første dagen kl. 00:00 UTC. Alle forespørsler med en nøkkel eller et OAuth-token fra organisasjonen teller, på hvilken som helst adresse. En forespørsel med strømming teller én gang, når den starter, uansett hvor lenge den varer; når kvoten er brukt opp, avvises den med 429 som alle andre forespørsler. En forespørsel som avvises med 429, teller ikke.

Headerne

Hvert svar på en forespørsel med en nøkkel har med seg grensene som gjelder for den:

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 og RateLimit følger IETF-utkastet RateLimit header fields for HTTP. Hvert element er én grense:

X-RateLimit-Limit, X-RateLimit-Remaining og X-RateLimit-Reset viser den strengeste av disse grensene i en enklere form, for klienter som ble skrevet før RateLimit fantes. X-RateLimit-Reset er i sekunder.

Når en grense er nådd

API-et svarer 429 Too Many Requests med en Retry-After-header 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…"
  }
}

Vent så mange sekunder som Retry-After angir, og gjenta forespørselen. Gjenta POST og PATCH med den samme Idempotency-Key. Hjelpefunksjonene for nye forsøk i Feil gjør begge deler.

Andre grenser i prisplanen svarer også 429 med Retry-After, for eksempel antall spørsmål per dag (limits.questions) eller antall svar som er under arbeid samtidig (limits.concurrent_answers). Håndter dem på samme måte.

Holde seg under grensene

• Les RateLimit, og senk tempoet når r blir lav, i stedet for å vente på en 429.
• Spre massearbeid utover tid, og bruk batch-operasjonene der de finnes: Én batch med 100 dokumenter er én forespørsel.
• Ikke spør etter endringer i en tett løkke. Abonner på webhooks, eller les hendelsesfeeden med noen sekunders mellomrom.
• Kjør parallelle arbeidsprosesser med en felles begrenser. Flere prosesser med én nøkkel deler én hastighetsgrense.
• Spør kontaktpersonen din hos Sursa om en høyere klasse hvis integrasjonen din trenger mer.