Limieten

#De limiet

Elke sleutel mag 120 aanroepen per minuut doen. De REST API en de MCP-server tellen in hetzelfde venster, dus een AI-assistent en een synchronisatie die één sleutel delen, delen ook de limiet; geef ze elk een eigen sleutel.

Een synchronisatie die 500 deelnemers per pagina leest, leest binnen de limiet 60.000 deelnemers, dus een goed gebouwde integratie loopt er zelden tegenaan. Een lus die steeds hetzelfde vraagt, loopt er binnen een minuut tegenaan, en daar is de limiet voor.

#Waar je staat

Elk antwoord, weigeringen inbegrepen, geeft de limiet in twee vormen mee: de RateLimit-headers van de IETF en de X-RateLimit-*-headers die de meeste clientbibliotheken lezen.

HTTP/1.1 200 OK
RateLimit-Policy: "default";q=120;w=60
RateLimit: "default";r=117;t=42
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 117
X-RateLimit-Reset: 42

r (remaining) is het aantal aanroepen dat in dit venster over is, en t het aantal seconden tot er een nieuw venster begint.

#Als je eroverheen gaat

De aanroep wordt geweigerd met 429 Too Many Requests, een header Retry-After in seconden en een probleem met "code": "rateLimited". Er is niets gedaan: wacht, en stuur hem dan opnieuw. Een geweigerde aanroep telt mee in de activiteit van sleutels, dus je ziet wanneer het gebeurde.

HTTP/1.1 429 Too Many Requests
Retry-After: 18
Content-Type: application/problem+json

{ "status": 429, "code": "rateLimited", "detail": "This key made more than 120 calls in a minute. Try again in 18 seconds; the RateLimit header says what is left." }

#Ruim binnen de limiet blijven

• Vraag om grote pagina's: limit=500 is prima.
• Synchroniseer met updatedSince in plaats van elke keer alles te lezen (Paginering en synchronisatie).
• Gebruik webhooks in plaats van pollen voor wat er net is gebeurd.
• Stuur If-None-Match mee met de ETag die je hebt: een 304 is snel, al telt hij wel mee.
• Pauzeer als de r van RateLimit laag wordt, in plaats van te wachten tot je wordt geweigerd.

Het venster wordt per server geteld, dus op een drukke dag kan een sleutel af en toe iets meer krijgen dan de limiet. Bouw daar niet op: beschouw de headers als de waarheid.