Snelheidslimieten en quota

Twee soorten limieten houden de API voor iedereen snel:

• De snelheidslimiet van een sleutel: hoeveel requests per seconde hij mag versturen, met een piek (burst) voor korte uitschieters.
• De quota van de organisatie: hoeveel requests al haar sleutels samen per minuut, per dag en per maand mogen versturen.

Beide hangen af van het abonnement van de organisatie. Elke response vertelt je waar je staat, dus een client die zich netjes gedraagt, hoeft nooit te gissen.

Snelheidslimiet van een sleutel

Elke sleutel krijgt een constant tempo en een piek. Met de piek kun je dat aantal requests in één keer versturen; daarna worden requests toegestaan in het constante tempo.

De klasse komt uit het abonnement van de organisatie. GET /v1/me toont de klasse, het tempo en de piek van de sleutel die het aanroept (rate_limit). De limiet geldt voor de sleutel als geheel, hoeveel API-servers je requests ook afhandelen.

De streaming-endpoints, POST /v1/chat (met of zonder "stream": true) en GET /v1/jobs/stream, vallen buiten de snelheidslimiet van de sleutel: ze verbruiken die niet, en hun RateLimit-headers hebben geen item "key". Ze tellen wel mee voor de quota van de organisatie, elk één keer, wanneer het request begint. Vragen hebben eigen limieten, die hieronder worden beschreven.

Quota van de organisatie

Een abonnement kan quota voor requests van de organisatie instellen: per minuut, per dag en per maand. De vensters zijn kalenderperioden in UTC: een minuut begint op :00 seconden, een dag om 00:00 UTC, een maand op de eerste dag om 00:00 UTC. Elk request met een sleutel of een OAuth-token van de organisatie telt mee, op elk adres. Een streamingrequest telt één keer mee, wanneer het begint, hoe lang het ook duurt; is een quotum op, dan wordt het net als elk ander request geweigerd met 429. Een request dat met 429 wordt geweigerd, telt niet mee.

De headers

Elke response op een request met een sleutel bevat de limieten die erop van toepassing zijn:

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 en RateLimit volgen het IETF-concept RateLimit header fields for HTTP. Elk item is één limiet:

X-RateLimit-Limit, X-RateLimit-Remaining en X-RateLimit-Reset melden de strengste van deze limieten in een eenvoudigere vorm, voor clients die zijn geschreven voordat RateLimit bestond. X-RateLimit-Reset is in seconden.

Als een limiet is bereikt

De API antwoordt met 429 Too Many Requests en een header Retry-After in seconden:

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

Wacht de tijd uit Retry-After af en herhaal het request. Herhaal POST en PATCH met dezelfde Idempotency-Key. De hulpfuncties voor nieuwe pogingen in Fouten doen allebei.

Andere limieten van het abonnement antwoorden ook met 429 en Retry-After, bijvoorbeeld het aantal vragen per dag (limits.questions) of het aantal antwoorden dat tegelijk in behandeling is (limits.concurrent_answers). Behandel ze op dezelfde manier.

Binnen de limieten blijven

• Lees RateLimit en vertraag als r laag wordt, in plaats van op een 429 te wachten.
• Spreid groot werk over de tijd en gebruik de batch-endpoints waar ze bestaan: één batch van 100 documenten is één request.
• Vraag niet in een snelle lus om wijzigingen. Abonneer je op webhooks of lees de eventfeed om de paar seconden.
• Laat parallelle workers een gedeelde snelheidsbegrenzer gebruiken. Meerdere processen met één sleutel delen één snelheidslimiet.
• Vraag je contactpersoon bij Sursa naar een hogere klasse als je integratie meer nodig heeft.