API Rate Limits, OAuth Tokens en Andere Integratie-Uitdagingen (Opgelost)

De Vijf Problemen Die Je Tegenkomt

Als je bedrijfssystemen via API's koppelt, loop je tegen dezelfde set problemen aan — ongeacht welke tools je integreert. We zijn ze allemaal tegengekomen in tientallen integratieprojecten, en we hebben betrouwbare oplossingen voor elk ervan. Dit artikel is de referentie die we zelf graag hadden gehad toen we begonnen.

1. OAuth Token-Verloop

Het Probleem

De meeste moderne API's gebruiken OAuth 2.0 voor authenticatie. Je krijgt een access token en een refresh token. Het access token verloopt — soms na een uur, soms na 10 minuten. Exact Online, dat veel voorkomt bij Nederlandse MKB-bedrijven, laat access tokens elke 10 minuten verlopen. Als je integratie dit niet correct afhandelt, faalt het stilletjes. De API retourneert een 401, je synchronisatie stopt, en niemand merkt het totdat een klant belt om te vragen waarom zijn factuur nooit is aangekomen.

Het refresh token heeft zijn eigen verlooptijd, vaak 30-60 dagen. Mis je dat venster, dan moet je handmatig opnieuw authenticeren via de browsergebaseerde OAuth-flow. Voor een systeem dat onbeheerd moet draaien, is dit een serieus probleem.

De Oplossing

Proactief vernieuwen. Wacht niet op een 401 om je token te vernieuwen. Houd de verlooptijd van het token bij en vernieuw 60-90 seconden voordat het verloopt. Dit elimineert het venster waarin je integratie draait met een verlopen token.

if (token.expires_at - current_time) < 90 seconds:
    refresh_token()

Refresh token-rotatie. Sommige API's (waaronder Exact Online) geven elke keer dat je het huidige refresh token gebruikt een nieuw refresh token uit. Sla het nieuwe refresh token direct en atomair op — als je opslagbewerking mislukt na de refresh-aanroep, ben je je enige geldige refresh token kwijt en moet je handmatig opnieuw authenticeren.

Alerting bij authenticatiefouten. Zelfs met proactief vernieuwen gaat er wel eens iets mis. De OAuth-provider heeft een storing. Een refresh token wordt server-side ongeldig gemaakt. Stel directe alerts in (e-mail, Slack, SMS) wanneer authenticatie mislukt — niet alleen logging. Het verschil tussen "we merkten het binnen 5 minuten" en "we merkten het na 3 dagen" is aanzienlijk.

Beveiliging van tokenopslag. Sla tokens versleuteld op (at rest). Log nooit volledige tokenwaarden. Gebruik een secrets manager of versleutelde database, geen platte tekst-configuratiebestanden. Dit is basisbeveiliging, maar we hebben het vaker fout dan goed zien gaan.

2. API Rate Limits

Het Probleem

Elke API heeft rate limits. Exact Online staat 60 requests per minuut per bedrijfsdivisie toe. Pipedrive staat 80 requests per 2 seconden toe op de meeste plannen. Shopify staat 40 requests per app per winkel toe. Als je deze overschrijdt, krijg je een 429-respons (Too Many Requests), en veel API's blokkeren je tijdelijk als je de limiet blijft bereiken.

De naïeve aanpak — "voeg gewoon een vertraging toe tussen requests" — werkt voor eenvoudige syncs maar valt uiteen als je meerdere integratieprocessen hebt die hetzelfde API-quotum delen, of wanneer je een initiële bulksync van duizenden records moet doen.

De Oplossing

Delta-sync, geen volledige sync. In plaats van elke keer alle records op te halen, houd je de laatste sync-timestamp bij en vraag je alleen records op die sindsdien zijn gewijzigd. Dit vermindert API-aanroepen met 90-99% tijdens normaal gebruik. De meeste API's ondersteunen modified_after of updated_since filters. Budget je rate limit voor normaal gebruik en je zult het zelden bereiken.

Gecentraliseerde rate tracking. Als meerdere processen dezelfde API aanroepen, moeten ze een rate limit-teller delen. Gebruik een gedeelde semafoor, een Redis-teller of een eenvoudige database-timestamp. Zonder dit denken Proces A en Proces B elk dat ze het volledige quotum hebben en overschrijden ze het gezamenlijk.

Respecteer Retry-After headers. Als je wél een rate limit bereikt, vertelt de API je meestal hoe lang je moet wachten via een Retry-After header. Gebruik die. Gok niet.

Exponential backoff met jitter. Voor retries zonder Retry-After header, gebruik je exponential backoff: wacht 1 seconde, dan 2, dan 4, dan 8, tot een maximum. Voeg willekeurige jitter toe (plus of min 20%) om thundering herd-problemen te voorkomen, waarbij meerdere processen tegelijkertijd opnieuw proberen.

Batch endpoints. Veel API's bieden batch endpoints waarmee je meerdere records kunt aanmaken, bijwerken of lezen in één enkel request. Eén batch-request voor 50 records gebruikt één rate limit-slot in plaats van 50. Controleer altijd de API-documentatie op batch-mogelijkheden voordat je een record-voor-record sync bouwt.

3. Omgaan met API-Downtime

Het Probleem

API's gaan down. Gepland onderhoud, onverwachte storingen, netwerkproblemen, DNS-fouten. Als je integratie een mislukte API-aanroep behandelt als een permanent falen, verlies je data. Als het oneindig opnieuw probeert zonder backoff, overspoelt je een herstellende service met requests en maak je het erger.

De Oplossing

Classificeer fouten. Niet alle fouten zijn hetzelfde:

• 4xx-fouten (behalve 429): Meestal jouw fout. Verkeerd request, ontbrekend veld, ongeldige data. Niet automatisch opnieuw proberen — fix het request.
• 429-fouten: Rate limit. Opnieuw proberen na de aangegeven vertraging.
• 5xx-fouten: Serverprobleem. Opnieuw proberen met exponential backoff.
• Timeouts: Netwerkprobleem. Eén keer direct opnieuw proberen, daarna backoff.

Implementeer een dead letter queue. Wanneer een request mislukt na alle retries (wij hanteren doorgaans maximaal 5 pogingen in 15 minuten), zet het dan in een dead letter queue voor handmatige inspectie in plaats van het te laten vallen. Een dead letter queue is simpelweg een wachtruimte — een databasetabel of een message queue — waar mislukte operaties wachten op menselijke beoordeling.

Circuit breaker-patroon. Als een API fouten retourneert bij 5 opeenvolgende aanroepen, stop dan met aanroepen voor een cooldown-periode (bijv. 5 minuten). Dit voorkomt dat je systeem resources verspilt door op een dood endpoint te hameren en geeft de API tijd om te herstellen. Na de cooldown stuur je één testrequest. Als dat slaagt, hervat je de normale operatie.

Statuspagina-monitoring. De meeste SaaS-API's publiceren een statuspagina. Monitor ze. Als Exact Online een storing meldt, kun je proactief syncs pauzeren in plaats van duizenden mislukte requests op te stapelen.

4. Dataformat-Mismatches

Het Probleem

Systeem A slaat telefoonnummers op als +31612345678. Systeem B slaat ze op als 06-12345678. Systeem C slaat ze op als (06) 1234 5678. Het is allemaal hetzelfde nummer, maar je deduplicatielogica denkt dat het drie verschillende contacten zijn.

Dit probleem strekt zich uit tot datums (ISO 8601 vs. DD/MM/YYYY vs. MM/DD/YYYY), valuta (centen vs. decimale euro's), adressen (één veld vs. gestructureerde velden) en vrijwel elk ander datatype dat geen universele standaard kent.

De Oplossing

Normaliseer aan de grens. Definieer een canoniek formaat voor elk datatype in je integratielaag. Telefoonnummers worden E.164-formaat (+31612345678). Datums worden ISO 8601. Bedragen worden integers in de kleinste valuta-eenheid (centen). Normaliseer inkomende data als eerste stap en denormaliseer uitgaande data als laatste stap.

Map velden expliciet. Neem nooit aan dat velden tussen systemen overeenkomen. Bouw en onderhoud een veldmappingdocument dat specificeert: bronveld, bestemmingsveld, transformatieregels, en wat te doen als het bronveld leeg is. Dit document wordt je single source of truth voor datatransformatie.

Valideer voor het schrijven. Na het transformeren van data, valideer je het tegen de vereisten van het bestemmingssysteem voordat je het API-verzoek verstuurt. Het opvangen van een ontbrekend verplicht veld of een ongeldige enum-waarde voordat het request verstuurd wordt, bespaart je een mislukte aanroep en een verwarrende foutmelding.

We behandelen veldmappingstrategieën en transformatiepatronen uitgebreider in onze gids over best practices voor systeemintegratie.

5. Webhook-Betrouwbaarheid

Het Probleem

Webhooks zijn de basis van real-time integraties. Systeem A stuurt een HTTP POST naar jouw endpoint als er iets gebeurt. Maar webhooks zijn fire-and-forget: de verzender doet één poging (soms een paar retries) en gaat verder. Als jouw endpoint down is, overbelast is, of een fout retourneert, mis je het event. Er is geen ingebouwd bevestigingsprotocol buiten de HTTP-responscode.

De Oplossing

Bevestig direct, verwerk later. Je webhook-endpoint moet binnen 1-2 seconden een 200 OK retourneren en de payload in een queue plaatsen voor verwerking. Als je probeert de webhook synchroon te verwerken — andere API's aanroepen, data transformeren, naar databases schrijven — riskeer je timeouts die de verzender interpreteert als een fout.

Implementeer idempotency. Webhooks kunnen meer dan eens afvuren voor hetzelfde event. Controleer altijd of je een event al hebt verwerkt voordat je erop handelt. Gebruik het event-ID of een hash van de payload als deduplicatiesleutel.

Reconciliatie-jobs. Zelfs met perfecte webhook-afhandeling, draai je een periodieke reconciliatie-job die records vergelijkt tussen systemen. Dit vangt alles op wat erdoorheen is geglipt: gemiste webhooks, verwerkingsfouten, race conditions. Wij draaien reconciliatie doorgaans elke 6-12 uur, afhankelijk van de datagevoeligheid.

Monitor webhook-vertraging. Houd de tijd bij tussen het moment dat een event plaatsvindt in het bronsysteem en het moment dat je integratie het verwerkt. Als deze vertraging toeneemt, heb je een queue-backup, een verwerkingsknelpunt of een gemiste webhook die downstream problemen opbouwt.

Beslissen of Je Het Zelf Bouwt

Als je overweegt of je API-integraties in-house moet bouwen of uitbesteden, zijn deze vijf problemen de werkelijke complexiteit. Het happy path — data lezen van de ene API en schrijven naar de andere — is eenvoudig. De engineering-inspanning zit in het afhandelen van de edge cases: het verlopen token om 3 uur 's nachts, de rate limit tijdens een bulkimport, de webhook die twee keer afvuurt.

Voor een uitgebreidere kijk op de build vs. buy-beslissing, inclusief kostenvergelijkingen op verschillende schalen, zie onze build vs. buy-analyse. En als je n8n als integratieplatform gebruikt, kunnen veel van deze patronen binnen de workflow-engine worden geïmplementeerd in plaats van helemaal vanaf nul.

De tools en patronen die hier beschreven worden, zijn goed ingeburgerd. De uitdaging is om ze allemaal consistent te implementeren over elk integratiepunt. Mis er één, en het wordt de failure mode die je op een zaterdagochtend wakker maakt.