Hastighedsgrænser og kvoter

To slags grænser holder API’et hurtigt for alle:

• En nøgles hastighedsgrænse: hvor mange anmodninger pr. sekund den må sende, med en burst til korte spidser.
• Organisationens kvoter: hvor mange anmodninger alle dens nøgler tilsammen må sende pr. minut, pr. dag og pr. måned.

Begge afhænger af organisationens prisplan. Hvert svar fortæller dig, hvor du står, så en klient, der opfører sig ordentligt, aldrig behøver at gætte.

En nøgles hastighedsgrænse

Hver nøgle får en jævn hastighed og en burst. Med en burst kan du sende så mange anmodninger på én gang; derefter tillades anmodninger i det jævne tempo.

Klassen afhænger af organisationens prisplan. GET /v1/me viser klasse, hastighed og burst for den nøgle, der kalder den (rate_limit). Grænsen gælder for nøglen som helhed, uanset hvor mange API-servere der betjener dine anmodninger.

Operationerne med streaming, POST /v1/chat (med eller uden "stream": true) og GET /v1/jobs/stream, ligger uden for nøglens hastighedsgrænse: De bruger den ikke op, og deres RateLimit-headere har intet "key"-element. De tæller dog med i organisationens kvoter, én gang hver, når anmodningen starter. Spørgsmål har deres egne grænser, som er beskrevet nedenfor.

Organisationens kvoter

En prisplan kan fastsætte kvoter for organisationens anmodninger: pr. minut, pr. dag og pr. måned. Vinduerne er kalenderperioder i UTC: Et minut begynder ved :00 sekunder, en dag kl. 00:00 UTC og en måned på den første dag kl. 00:00 UTC. Alle anmodninger med en af organisationens nøgler eller OAuth-tokens tæller med, uanset adresse. En streaming-anmodning tæller én gang, når den starter, uanset hvor længe den varer; er kvoten brugt op, afvises den med 429 som enhver anden anmodning. En anmodning, der afvises med 429, tæller ikke med.

Headerne

Hvert svar på en anmodning med en nøgle viser de grænser, der gælder 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-udkastet RateLimit header fields for HTTP. Hvert element er én grænse:

X-RateLimit-Limit, X-RateLimit-Remaining og X-RateLimit-Reset viser den strengeste af disse grænser i en enklere form til klienter, der blev skrevet, før RateLimit fandtes. X-RateLimit-Reset er i sekunder.

Når en grænse er nået

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 det antal sekunder, der står i Retry-After, og gentag anmodningen. Gentag POST og PATCH med den samme Idempotency-Key. Hjælpefunktionerne til nye forsøg i Fejl gør begge dele.

Andre grænser i prisplanen svarer også 429 med Retry-After, fx antallet af spørgsmål pr. dag (limits.questions) eller antallet af svar, der er i gang på samme tid (limits.concurrent_answers). Håndtér dem på samme måde.

Sådan holder du dig under grænserne

• Læs RateLimit, og sænk tempoet, når r bliver lav, i stedet for at vente på en 429.
• Fordel massearbejde over tid, og brug batch-operationerne, hvor de findes: Én batch med 100 dokumenter er én anmodning.
• Spørg ikke efter ændringer i en tæt løkke. Abonnér på webhooks, eller læs hændelsesfeedet med få sekunders mellemrum.
• Kør parallelle workers med en fælles begrænser. Flere processer med én nøgle deler én hastighedsgrænse.
• Spørg din kontaktperson hos Sursa om en højere klasse, hvis din integration har brug for mere.