API-rate limits begrenzen hoeveel verzoeken een systeem binnen een bepaalde periode verwerkt. Je leest hoe limieten worden toegepast, wat foutmeldingen en responseheaders vertellen en hoe je retries, wachtrijen en back-off zo inricht dat tijdelijke drukte niet uitgroeit tot een storing.
Wat een API-rate limit precies begrenst
Een API-rate limit bepaalt hoeveel verzoeken je binnen een bepaalde tijdspanne mag doen. Zo'n limiet verdeelt schaarse capaciteit over alle gebruikers en voorkomt misbruik. De grens werkt soms per seconde, per minuut, uur of dag, of zelfs per endpoint of soort actie. Voorbeeld: een leesactie valt vaak onder een andere limiet dan een zware export waar veel databasewerk bij komt kijken.
De gekozen periode vertelt niet altijd hoe je limiet wordt geteld. Met een vaste teller start voor elke minuut het aantal opnieuw. Je kunt dan vóór en vlak nadat de klok verspringt samen toch meer dan je verwacht. Bij een rolling window wordt elke aanvraag op een schuivend tijdsblok getoetst. Een token bucket geeft je ruimte om even te pieken, zolang je niet eerder alles opgemaakt hebt. Het ene model wijst aanvragen af die het andere nog doorlaat, zelfs bij dezelfde gemiddelde snelheid.
Let op het verschil tussen rate limits en quota. Een rate limit remt je snelheid, een quota kan je dagelijkse of maandelijkse totaal beperken. Ontwerp clients dus niet alleen op "zoveel per minuut". Bekijk welke endpoints je aanroept, wat de documentatie zegt over grenzen en of die per gebruiker, app of account gelden. Mis je die nuance, dan krijg je gegarandeerd pieken die de limiet rammen. Gebruik je periodiek pollen? Lees ook over webhooks of pollen.
HTTP 429 en andere signalen van limietoverschrijding
De bekendste code bij te veel verzoeken is 429 Too Many Requests. Zie je die, dan ben je te snel gegaan. Soms krijg je een Retry-After-header mee met een tijd of aantal seconden: daar mag je pas na opnieuw proberen. Gebruik die als-ie er staat, maar lees de documentatie: niet iedere API doet 't hetzelfde of heeft deze header.
Een weigering komt niet altijd als 429. Soms gooit een gateway een 503 Service Unavailable je kant op bij drukte, of vind je alleen een eigen code in de responsebody. 403 betekent meestal geen toegang, maar bij sommige diensten staat het toch voor een opgebruikte grens. Dus check altijd: is het echt een rate limit? Combineer statuscode met headers, codes en documentatie voordat je probeert een retry-loop te bouwen.
Headers over je resterende capaciteit of het tijdstip van resetten zijn handig, maar niet altijd beschikbaar en vaak anders benoemd. Een API kan nog laten zien hoeveel verzoeken je mag doen en wanneer je teller weer wordt aangevuld; een andere toont niks, of geeft alleen data op accountniveau. Log bij fouten de relevante headers, codes, endpoint mee, maar slaat tokens en gevoelige gegevens over. Zo zie je of problemen komen door je eigen piek, iets wat het hele account raakt, of serverdrukte ergens verderop.
Verschillende limieten per gebruiker, sleutel en endpoint
Limieten kunnen tegelijk op meerdere plekken gelden. Sommige providers tellen per API-sleutel, gebruiker, IP, organisatie of per endpoint. Bovenop kan er een totaalplafond zitten voor het hele account. Houd je alleen één limiet bij maar draai je met meerdere processen op dezelfde sleutel, dan krijg je alsnog afwijzingen over je hele systeem. Vooral als achtergrondtaken, batchjobs of gebruikersinterfaces samen dezelfde capaciteit benutten, heb je dit snel te pakken.
De gekozen scope bepaalt of je processen van elkaar op de hoogte moeten zijn. Iedereen lokaal laten tellen werkt niet als ze samen de accountlimiet overschrijden. Dan heb je dus een centrale limiter nodig, bijvoorbeeld via een gedeelde database. Bij een eigen API-sleutel per worker kun je vaak wel per worker limiteren. De aanpak stuurt de complexiteit en het risico op onverwachte weigeringen of ongebruikte ruimte.
Check of verschillende acties een verschillend gewicht hebben. Eén verzoek kan bij de ene API zwaarder tellen (door bijvoorbeeld een omvangrijke zoekopdracht), terwijl een batch in één call toch veel capaciteit gebruikt. Neem het gewicht en de scope mee in je logging. Zonder dat spoor je niet waarom je prima onder het aantal requests zit maar toch over je limiet gaat. Ook bij automatiseren met AI moeten processen die dezelfde sleutel delen samen worden begrensd.
Retries met exponentiële back-off en jitter
Een retry werkt alleen als de fout tijdelijk is. Komen rate limits in beeld, dan moet je pauzeren voor je het opnieuw probeert. Meteen herhalen leidt tot meer weigeringen en extra druk. Exponentiële back-off betekent dat de wachttijd per mislukte poging langer wordt, meestal tot een vastgesteld maximum. Pak de Retry-After-header waar mogelijk als minimale wachttijd.
Gebruik ook jitter: voeg willekeur toe aan je wachttijd. Anders proberen massa's clients tegelijk opnieuw als ze allemaal een fout tegelijk zien, en krijg je een retrystorm die de boel nog zwaarder belast. Jitter verdeelt de pogingen over de tijd. Vaak kies je een willekeurige tijd tussen 0 en de maximale back-off. Kies alleen wat past bij de eisen van je API en de minimumwachttijd die geldt.
Er moet altijd een grens aan het aantal retries zitten. Stuur een verzoek na meerdere fouten naar een aparte foutafhandeling of meld het aan monitoring. Laat het niet eindeloos in een retry-loop hangen. Zorg dat je geen retries uitvoert op fouten die niet kunnen herstellen, zoals invalid input of een niet-toegestane actie. Ongecontroleerd opnieuw proberen bij elke niet-200-code helpt niemand en maskeert echte fouten. Zet retryvoorwaarden expliciet, en log telkens waarom je opnieuw probeert.
Wachtrijen gebruiken om verzoekpieken af te vlakken
Met een wachtrij koppel je het ontstaan van werk los van de daadwerkelijke API-call. Dus als er plots veel te doen is, gooi je de taken in een queue. Workers halen taken er in eigen tempo uit en houden zich aan je ingestelde snelheid. Zo blijft je API-verkeer gelijkmatiger en benut je je limiet gecontroleerd. Vooral geschikt voor achtergrondwerk, zoals synchroniseren, rapporteren of batchen, waar instant resultaat niet hoeft. Bij webshopvoorraadsynchronisatie helpt een queue om pieken in updates af te vlakken.
Een queue is geen oplossing bij structureel te weinig capaciteit. Komt er lange tijd meer binnen dan workers wegwerken, dan groeit de queue en neemt de wachttijd toe. Meet daarom hoeveel taken op voorraad staan, hoe oud de oudste zijn en hoe snel taken wegwerken lukt. Stel limieten in, bepaal wat te doen als de queue volloopt: block je de instroom, wijst je taken af, of laat je ze gecontroleerd verlopen? Zonder limiet riskeer je bij een API-storing een vastlopende of uitputtende applicatie.
Zet prioriteit op taken als dat zinvol is. Een gebruikerstaak wil je misschien sneller afhandelen dan routineonderhoud. Maar let op: alleen hoge prioriteiten betekent op den duur dat je lage taken niet meer wegwerkt. Overweeg aparte queues of een scheduling die minder dominante taken ook aan bod laat komen, met zicht op alle limieten die je deelt. De queue bepaalt volgorde en buffering; de rate limiter bepaalt wie wanneer mag versturen. Voor n8n-workflows geldt hetzelfde: begrens workers en houd retries eindig.
Verzoektempo regelen met token bucket en concurrency limits
Wil je liever voorkomen dat elk verzoek pas wordt geweigerd ná verzending, dan zet je een limiter aan clientzijde. De token-bucket-methode werkt als volgt: je verzamelt tokens in een bakje, elk verzoek kost een token, en tokens worden periodiek aangevuld. Pieken zijn toegestaan zolang je de bakje niet hebt leeggehaald. Een leaky bucket forceert juist een stabiel uitstroomtempo, zonder ruimte om te pieken. Welke past ligt aan of de API pieken accepteert of juist een constante stroom verwacht.
Let op het verschil tussen een snelheidslimiet en het maximale aantal gelijktijdige verzoeken. De eerste remt het aantal starts per tijdseenheid; de tweede het totaal actieve verzoeken tegelijk. Is de server langzaam, dan levert alleen een snelheidslimiet alsnog veel parallelle connecties op. Is de server juist snel, dan kan te streng limiteren op gelijktijdigheid capaciteit weggooien. Meet responstijden en stel je limieten bij op praktijk en eisen.
Gebruik je meerdere processen, dan moet je weten waar de limiter zijn werk doet. Zet je per worker een eigen limiter aan, dan kun je de limiet per ongeluk vermenigvuldigen met het aantal processen. Met centraal limiteren voorkom je dat, maar introduceer je wel een afhankelijkheid. Bij storing is er de keuze: open laten zodat alles doorloopt, of dicht zodat alles stopt. Welke optie je kiest, hoort een bewuste ontwerpbeslissing te zijn.
Idempotentie en veilige verwerking van opnieuw verzonden verzoeken
Na een timeout weet een client vaak niet of een actie wel of niet door de API is uitgevoerd. Misschien is je order al geregistreerd, maar ging de response onderweg verloren. Nog een keer versturen betekent dan dubbel uitvoeren, wat je vooral bij betalingen, ordercreatie of berichten wilt vermijden. Dit probleem speelt los van rate limits, maar wordt zichtbaarder als je automatisch retries inzet.
Een actie is idempotent als herhalen met dezelfde input altijd hetzelfde uitpakt als één keer uitvoeren. GET hoort geen data te wijzigen; een PUT stelt meestal gewoon nogmaals die waarde in. POST-acties zijn vaak niet idempotent: je maakt een nieuw object. Ondersteunt de API een idempotency key, geef dan steeds bij hetzelfde verzoek die unieke sleutel mee. De server merkt dan op dat-ie dit verzoek al gehad heeft en kan het originele resultaat teruggeven.
Check hoelang de API idempotency keys bewaart en wat-ie doet bij een sleutel met andere data. Bewaar de sleutel vast bij de taak, zodat een worker na een herstart niet stilletjes een request dubbel doet. Biedt de API geen ondersteuning hiervoor, neem dan zelf een stap op om eerst te controleren of het gewenste resultaat al bestaat. Anders krijg je zomaar dubbele orders die later lastig te onderscheiden zijn van geldige transacties.
Rate limits monitoren en retrygedrag testen
Je beheert pas goed als je ziet hoe vaak je tegen rate limits aanloopt. Houd bij hoe vaak je 429-responses krijgt, retries per aanvraag, hoeveel tijd verloren gaat aan wachten en hoeveel verzoeken alsnog niet slagen. Splits waar kan per endpoint en integratie, maar voorkom API-sleutels of gevoelige data in metric-labels. Te veel unieke labels maken je metrics onbruikbaar en monitoring zwaar.
Leg retries vast per trace of taak, inclusief het nummer van de poging, de wachttijd en reden van retry. Zo zie je of je ergens één weigering oplost of vastzit in een vicieuze cirkel. Zie je veel retries, kan dat komen door een foute limiter, tegelijk gebruik door meerdere apps of een trage API. Alleen het eindresultaat loggen maskeert onderliggende druk.
Test expres op limietgedrag. Een mockserver kun je zo instellen dat hij 429’s, wisselende Retry-After-tijden, timeouts of 503’s teruggeeft. Controleer dat clients wachten, jitter gebruiken, ergens stoppen en de wachtrij niet onbeperkt laten groeien. Test parallelle workers, want een limiter die lokaal goed werkt, kan bij schaal alsnog het totaal overschrijden. Voeg in dashboards zowel fouten als queue-wachttijden toe, want een lage foutscore maskeert wachtrijen die steeds voller raken.
Veelgestelde vragen
Hoe kan ik het aantal API-verzoeken verlagen zonder functionaliteit te verliezen?
Het aantal API-verzoeken kun je beperken door caching in te zetten en dubbele aanvragen uit te sluiten. Kijk naar welke data je veilig lokaal kunt opslaan, en hoe lang die bruikbaar is.
- Cache gegevens die niet vaak veranderen, stel een houdbaarheid in die logisch is.
- Haal waar mogelijk meerdere resultaten in één aanvraag op of vraag alleen het verschil t.o.v. vorige keer.
- Laat niet toe dat verschillende onderdelen tegelijk identieke data ophalen.
- Gebruik conditionele requests als de API ETag of Last-Modified ondersteunt.
Check na je aanpassingen of data nog voldoende actueel is. Langere cache-interval betekent minder verkeer, maar vergroot kans op verouderde gegevens voor de gebruiker.
Wat doe ik als een API-provider geen exacte rate limit publiceert?
Krijg je geen limieten te zien van de provider, bouw dan voorzichtig op. Start traag, en pas op wanneer je hoger gaat zitten als alles soepel blijft werken.
- Vraag de provider naar grenzen, scope en voorwaarden, als je daar antwoord op kunt krijgen.
- Begin met lage snelheid, monitor op 429’s, timeouts en wisselende responstijden.
- Zodra afwijzingen binnenkomen, laat je tempo direct zakken; verhogen doe je langzaam pas na een stabiele periode.
- Test liever met een sandbox of een nagebootste server dan live op productie te gaan gokken.
Ga er niet zomaar van uit dat geen fouten ook geen limiet betekent. Soms verschillen limieten per endpoint, of zijn ze afhankelijk van belasting en hoeveel je account of andere klanten op dat moment gebruiken.
Hoe voorkom ik dat API-limieten van meerdere gebruikers mijn frontend verstoren?
Voorkom problemen in je frontend door limieten centraal op de serverkant te beheren. Geef niet iedere browser losse toegang met een gedeelde API-sleutel.
- Houd gevoelige API-sleutels op je backend, stuur ze nooit door naar frontend.
- Laat de backend verzoeken spreiden en stel vast hoe je capaciteit per gebruiker verdeelt.
- Zorg indien nodig voor limieten per gebruiker, zodat iemand niet onevenredig veel quota opslokt.
- Laat de frontend weten als verzoeken later worden verwerkt of (tijdelijk) niet kunnen doorgaan.
Achter de backend kunnen alsnog problemen ontstaan als meerdere servers of processen dezelfde quota delen. De centrale throttling moet ook met alle clients rekening houden die tegelijk het limiet gebruiken.
Wat moet een gebruiker zien als een API-verzoek door een rate limit wordt uitgesteld?
Geef duidelijk aan dat het langer duurt en toon een status, niet zomaar een draaiend wieltje zonder uitleg.
- Toon bij achtergrondtaken dat de opdracht in een wachtrij staat.
- Laat live voortgang of een statuspagina zien bij werk dat uit meerdere stappen bestaat of veel tijd kost.
- Bied een manier om een seintje te krijgen als het klaar is, of om het later terug te zien.
- Voorkom dat gebruikers door herhaald klikken onbedoeld extra taken starten.
Wees terughoudend met het geven van exacte wachttijd als die niet betrouwbaar te voorspellen is. Zeg of de gebruiker de pagina mag verlaten en wat er gebeurt als het werk mislukt.
Wanneer moet ik een waarschuwing instellen voor API-rate limits?
Zet waarschuwingen aan als rate limits merkbaar worden voor gebruikers of als je structureel dicht op je grens zit.
- Waarschuw bij een aanhoudende golf aan 429’s, niet bij elk los incident.
- Bekijk het retrypercentage, cumulatieve wachttijd en het aantal mislukkingen ook.
- Splits alarmen per endpoint of integratie waar handig, zodat je sneller weet wie of wat het probleem is.
- Maak verschil tussen een eenmalige piek en iets dat langdurig is, want alleen dat laatste vraagt om actie.
Bepaal je drempels aan de hand van standaard gebruik en wat uitval betekent. Voorkom dat elke 429 een alarm start, anders verdrink je in meldingen en mis je echte problemen.
Foto: Aayush Srivastava