Rate limits en throttling: wat gebeurt er als een API "te veel" zegt

Wat een rate limit is

Een API bedient veel afnemers tegelijk op dezelfde servers. De rate limit zorgt ervoor dat één afnemer de rest niet vertraagt. Voor een koppeling is het een vast gegeven: zoveel aanroepen per minuut, per dag of tegelijk, en niet meer.

Raak je de grens, dan antwoordt de API met status 429 Too Many Requests. Die status staat in RFC 6585, sectie 4. Het antwoord mag een Retry-After header bevatten die zegt hoe lang je moet wachten.

Veel API's melden het saldo al voordat het op is. Exact Online stuurt bij elk antwoord vijf headers mee. Na de zestigste aanroep binnen een minuut staan ze zo, met voorbeeldwaarden:

HTTP/1.1 200 OK
X-RateLimit-Minutely-Limit: 60
X-RateLimit-Minutely-Remaining: 0
X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 3841
X-RateLimit-Reset: 1791072000000

De minuutlimiet is op, van de daglimiet zijn er nog 3.841 over. Elke volgende aanroep in dezelfde minuut krijgt een 429. X-RateLimit-Reset is het moment waarop het dagvenster opnieuw begint, in milliseconden sinds 1 januari 1970 UTC.

Limieten komen in vier vormen voor:

Limieten per systeem

De getallen komen uit de documentatie van de leveranciers, gecontroleerd op 3 oktober 2026.

Vier dingen in deze tabel gaan in de praktijk mis.

Shopify GraphQL antwoordt met 200. Een afgeknepen query komt terug als een geslaagd HTTP-antwoord met "code": "THROTTLED" in de body. Een koppeling die alleen naar de statuscode kijkt, boekt de aanroep als gelukt en de voorraadwijziging is nooit aangekomen.

NetSuite geeft een 400. Een RESTlet die het maximum aan gelijktijdige aanvragen raakt, antwoordt met 400 Bad Request en de foutcode SSS_REQUEST_LIMIT_EXCEEDED. Dat is dezelfde status als bij een fout in de data. De koppeling moet de foutcode lezen om te weten dat opnieuw proberen hier zin heeft. Het maximum geldt per account en wordt gedeeld met elke andere koppeling die daar draait.

Exact Online telt ook fouten. Naast de aanroepen geldt een grens van 10 fouten per uur per endpoint, waarbij 400, 401, 403 en 404 meetellen. Een koppeling die een afgekeurde order blijft aanbieden, blokkeert zichzelf voor een uur. Exact beschrijft dit op de pagina API limits.

WooCommerce begrenst alleen de Store API. Die limiet bestaat sinds WooCommerce 7.2, geldt voor POST-aanvragen en staat standaard uit. De documentatie van de REST API waar een koppeling orders en producten mee leest, noemt geen limiet. Daar bepaalt de server van je hostingpartij hoeveel verkeer hij aankan, en een trage server geeft een timeout in plaats van een 429.

AFAS Profit publiceert geen getal. Er geldt een fair-use-beleid, en een GetConnector geeft zonder take-parameter de eerste 100 regels terug. Een koppeling die dat niet weet, synchroniseert 100 artikelen en meldt dat alles gelukt is.

Wat een koppeling doet bij een 429

De aanroep is niet verwerkt. De koppeling moet hem bewaren, wachten en opnieuw aanbieden. Hoe lang wachten hangt af van de vorm van de limiet.

Neem de lekkende emmer van de REST API van Shopify: 40 groot, 2 per seconde eruit. Er komen 100 orderstatussen tegelijk klaar te staan.

• De eerste 40 gaan direct door. De emmer is vol.
• Aanroep 41 krijgt een 429 met Retry-After: 2.0.
• De overige 60 kunnen met 2 per seconde: 60 / 2 = 30 seconden.

Een koppeling met een wachtrij verstuurt de 60 in dat tempo en is na 30 seconden klaar, zonder één fout. Zonder wachtrij zijn er 60 aanroepen geweigerd en hangt het van de foutafhandeling af of ze ooit nog aankomen.

Geeft de API geen Retry-After mee, dan wacht de koppeling met groeiende pauzes: 1 seconde, dan 2, 4, 8 en 16. Vijf pogingen kosten samen 1 + 2 + 4 + 8 + 16 = 31 seconden. Bij een vast venster zoals de minuutlimiet van Exact Online heeft sneller proberen geen zin: de ruimte komt pas terug als de minuut om is.

Wat na het laatste aantal pogingen nog faalt, gaat met het originele bericht naar een aparte lijst. Daar blijft het staan tot de oorzaak is opgelost en het opnieuw verwerkt kan worden. Een herhaalde aanroep mag geen tweede order opleveren. Hoe je dat voorkomt staat in dubbele klanten en debiteuren.

Limieten ontwerpen in plaats van ontdekken

Een limiet die je op de drukste dag ontdekt, kost orders. De som maak je vooraf.

Polling verbruikt budget zonder dat er iets verandert. Vier endpoints die elke minuut bevraagd worden, zijn 4 x 1.440 = 5.760 aanroepen per dag. Dat is meer dan de 5.000 van Exact Online, voordat er één order geschreven is. Elke 5 minuten is 4 x 288 = 1.152. Waar het systeem een webhook biedt, vervalt het vragen grotendeels.

Eén sleutel, twee koppelingen. De limiet van Exact Online geldt per app per administratie, die van Picqer per API-sleutel. Twee processen op dezelfde sleutel delen hetzelfde budget en weten niet van elkaar wat ze verbruiken. Zelf meetellen klopt dan niet meer. De koppeling leest het resterende saldo uit de headers van elk antwoord.

Een budget per stroom. Van 5.000 per dag gaat een vast deel naar orders, een deel naar voorraad en de rest naar artikelgegevens. Orders gaan voor: een volledige artikelronde wacht als het saldo onder een drempel komt. De rekensom per stroom staat in doorvoer berekenen.

Foutmeldingen die iets anders zeggen. Niet elke tussenlaag geeft een limiet ongewijzigd door. Er zijn koppelplatformen die een bereikte limiet tonen als Ratelimit exceeded met foutcode UNAUTHORIZED. Wie alleen de code leest, gaat zoeken naar een verlopen wachtwoord.

Wat betekent dit voor je koppeling?

Wij bouwen elke koppeling met een wachtrij tussen de systemen. Aanroepen gaan in het tempo dat de API toelaat, een 429 leidt tot wachten en een nieuwe poging, en wat blijft falen staat met het originele bericht op een lijst die je in het dashboard ziet. De limieten van jouw systemen en je aantallen op een piekdag bepalen hoe de stromen verdeeld worden.

De basis staat in wat is een API koppeling, de bewaking op monitoring van je koppeling en het overzicht op koppelingen. Wil je weten waar jouw systemen de grens leggen, stuur ze dan in.