Foutmeldingen leren lezen: wat 400, 401, 429 en 500 betekenen bij een koppeling

Door Clen Mourik

Je koppeling stopt plotseling met werken. Een foutcode verschijnt. Maar wat betekent die eigenlijk? En belangrijker: kun jij het zelf oplossen, of ligt het bij de andere partij? Leer de vier belangrijkste HTTP-foutcodes herkennen en wat je ermee moet.

Hoeveel uur heb jij verspild aan een koppeling die ineens niet meer werkt? Je opent maandagochtend je laptop, en orders die normaal automatisch doorkomen naar je boekhouding... staan stil. Facturen die altijd netjes naar AFAS gingen? Vastgelopen. Je ziet een foutmelding met cijfers: 401, 429, 500.

De meeste ondernemers staren naar zo'n foutcode alsof het Chinees is. En dat is logisch — je hebt een bedrijf te runnen, geen IT-opleiding gevolgd. Maar hier zit het probleem: zonder te weten wat die codes betekenen, weet je niet of je vijf minuten een instelling moet aanpassen, of dat de serverboerderij van je softwareleverancier in brand staat.

In dit artikel leg ik de vier belangrijkste HTTP-foutcodes uit die je tegenkomt bij koppelingen tussen systemen. Gewoon Nederlands. Zodat je weet wanneer je zelf aan de knoppen moet draaien, en wanneer je de telefoon moet pakken.

Inhoudsopgave

• Belangrijkste punten
• Wat zijn HTTP-foutcodes eigenlijk?
• Foutcode 400: Bad Request — je stuurt iets fout
• Foutcode 401: Unauthorized — geen toegang
• Foutcode 429: Too Many Requests — te veel haast
• Foutcode 500: Internal Server Error — hun probleem (meestal)
• Praktijkvoorbeelden uit verschillende sectoren
• Wat moet je doen bij welke fout?
• Veelgemaakte fouten die het erger maken
• Voorkomen is beter dan genezen
• Veelgestelde vragen

Belangrijkste punten

Wat zijn HTTP-foutcodes eigenlijk?

Je systemen praten met elkaar via internet. Een API is gewoon een manier waarop software vraagt: "Hé, kun je me die factuurgegevens sturen?" of "Hier heb je een nieuwe order, zet 'm in je systeem."

Elke keer dat zo'n vraag wordt gesteld, komt er een antwoord terug. Dat antwoord heeft altijd een nummer. Dat nummer heet een HTTP-statuscode. Het is eigenlijk een soort briefje erbij: "Gelukt" (200), "Niet gevonden" (404), of "Sorry, kan ik niet" (500).

De basisregel is simpel: codes met een 400-waarde wijzen op fouten aan jouw kant (de client), en codes met een 500-waarde wijzen op fouten aan de server-kant (Hostragons). Dit is de meest fundamentele vuistregel.

In de praktijk kom je bij koppelingen vier codes het vaakst tegen:

• 400 Bad Request — je vraag klopt niet (verkeerd formaat, ontbrekend veld)
• 401 Unauthorized — je hebt geen toegang (verkeerd wachtwoord, verlopen token)
• 429 Too Many Requests — je vraagt te veel tegelijk (rate limit bereikt)
• 500 Internal Server Error — hun kant heeft een probleem (of bij AFAS: jouw data klopt inhoudelijk niet)

Laten we ze één voor één doornemen.

Foutcode 400: Bad Request — je stuurt iets fout

Een 400-fout betekent: de server snapt niet wat je vraagt. Alsof je een formulier instuurt waar de helft van de velden leeg is, of waar je letters invult waar getallen moeten staan.

Veelvoorkomende oorzaken bij koppelingen:

• Een verplicht veld ontbreekt (bijvoorbeeld: je stuurt een order zonder klantnummer)
• Verkeerd datatype (je stuurt tekst waar een getal moet staan)
• Onjuist geformatteerde JSON (een komma te veel, een haakje vergeten)
• Te lange waarde voor een veld (AFAS verwacht maximaal 4 cijfers, jij stuurt er 5)

Bij AFAS krijg je vaak een 400 als je een paar verplichte velden vergeten bent te vullen (STKKR). Of als je een type mismatch hebt — bijvoorbeeld een tekstuele waarde in een numeriek veld probeert te stoppen.

Wat ik in de praktijk zie: bij 8 van de 10 klanten die een 400-fout krijgen, ligt het aan een wijziging in hun bronsysteem. Iemand heeft een verplicht veld toegevoegd in AFAS, maar de koppeling stuurt dat veld niet mee.

De oplossing? Check de foutmelding zelf. Die vertelt vaak precies wat er mis is: "Veld 'DebiteurNummer' is verplicht" of "Waarde te lang voor veld X". Pas je data aan, of pas de koppeling aan zodat het veld wél wordt meegestuurd.

Belangrijk: opnieuw proberen heeft bij een 400-fout geen enkele zin. Je stuurt dezelfde foute data opnieuw. Fix eerst de data.

Foutcode 401: Unauthorized — geen toegang

Een 401-fout betekent: je mag hier niet binnen. De deur zit op slot, of je hebt de verkeerde sleutel.

Dit is vaak de meest frustrerende fout, omdat de koppeling gisteren nog werkte. Wat is er gebeurd?

Veelvoorkomende oorzaken:

• Een OAuth-token is verlopen (veel tokens zijn 90 dagen geldig)
• De gebruiker op wiens naam de koppeling draait, is geblokkeerd of heeft geen rechten meer
• Een wachtwoord is gewijzigd (en de koppeling weet dit niet)
• De API-sleutel is ingetrokken of opnieuw gegenereerd

Bij Exact Online zie je dit vaak na een reorganisatie. De medewerker die de koppeling heeft geautoriseerd, is uit dienst. Het account is geblokkeerd. De koppeling valt stil (Simplicate Help).

De praktische tip: kies iemand die langdurig bij de organisatie blijft om de OAuth-autorisatie te doen. Niet de stagiair. Niet de medewerker die over drie maanden vertrekt. De eigenaar of een vaste kracht.

Bij AFAS betekent een 401 meestal dat de AppConnector is geblokkeerd of dat de gekoppelde gebruiker geblokkeerd is (AFAS Help Center). De oplossing: genereer een nieuw token in AFAS.

Check ook altijd: heeft de gebruiker toegang tot de juiste administratie (division code bij Exact Online) en de juiste rechten (mag die gebruiker facturen aanmaken, orders wijzigen, etc.)?

Foutcode 429: Too Many Requests — te veel haast

Dit is de enige 4xx-fout waar opnieuw proberen wél zinvol is. Maar dan met mate.

Een 429-fout betekent: je vraagt te veel tegelijk. De API-provider heeft een limiet ingesteld hoeveel verzoeken je per minuut of per dag mag doen. Je hebt die limiet bereikt.

Exact Online hanteert bijvoorbeeld twee rate limits: minimaal 60 API-calls per bedrijf per minuut, en een dagelijkse limiet van 50.000 API-calls per bedrijf per dag (Brixxs FAQ). En dat gaat nog omlaag: in de loop van het jaar wil Exact Online de daglimiet verlagen van 50.000 naar 5.000 aanvragen per bedrijf.

Stel je voor: je hebt een applicatie die elke minuut de laatste 10 facturen uit Exact Online ophaalt. Dat zijn al 600 calls per uur. Tel daar je andere koppelingen bij op (CRM, webshop, voorraadsysteem), en je zit snel aan je limiet.

Wat gebeurt er als je de limiet bereikt? Zodra een app de dagelijkse limiet voor een bedrijf overschrijdt, worden API-oproepen voor dat bedrijf afgewezen en krijg je een HTTP 429. De app kan nog steeds verzoeken versturen voor andere bedrijven, maar voor dit specifieke bedrijf zit je vast tot het volgende dagvenster.

Doorgaan met calls maken na het bereiken van de daglimiet heeft geen zin. Deze worden geweigerd totdat het tariefvenster aan het begin van de volgende dag wordt gereset (Brixxs FAQ).

De oplossing bij een 429:

• Gebruik exponential backoff: wacht 1 seconde, dan 2, dan 4, dan 8
• Respecteer de Retry-After header (als die aanwezig is, staat daar hoelang je moet wachten)
• Optimaliseer je API-gebruik: haal zoveel mogelijk data in één call op, in plaats van 100 losse calls
• Gebruik caching: sla data lokaal op, zodat je niet steeds opnieuw dezelfde gegevens hoeft op te halen
• Vermijd piekuren (Exact Online raadt aan calls tussen 04:00-04:30 CET te vermijden vanwege onderhoud)

Een klant van ons draaide een batchsynchronisatie elke nacht om 03:00. Perfect toch? Tot Exact de daglimiet verlaagde en de batch halverwege vastliep. We hebben het gesplitst over de dag, kleinere pakketjes. Probleem opgelost.

Foutcode 500: Internal Server Error — hun probleem (meestal)

Een 500-fout betekent in theorie: de server heeft een onverwachte fout. Iets ging mis op hun kant. Jij kunt er niks aan doen.

Maar hier wordt het ingewikkeld, want niet elk systeem gebruikt een 500 op dezelfde manier.

Bij Exact Online betekent een 500 meestal echt een serverstoring of een bug. De melding luidt vaak: "A problem has occurred. The cause of this issue will be investigated as soon as possible." Dit moet je melden bij Exact API Support (Exact Online Knowledge Base).

Bij AFAS daarentegen betekent een 500-fout iets heel anders. Het is géén serverstoring, maar een inhoudelijke bedrijfslogica-fout (AFAS Help Center). AFAS geeft aan: "HTTP 500 bij AFAS geeft aan dat er wel verbinding is gemaakt met AFAS, maar dat de request inhoudelijk wordt afgekeurd. Je krijgt in de response een bericht met beknopte uitleg en een verwijzing naar het Profit logboek."

Praktijkvoorbeeld bij AFAS: je probeert een afspraak aan te maken, maar je hebt geen genodigden toegevoegd. AFAS weigert de request met een 500-fout en de melding: "General message: Om een afspraak aan te maken dienen er genodigden te zijn." Dat is geen bug. Dat is jouw data die niet voldoet aan de bedrijfsregels.

Dit verschil is cruciaal. Bij Exact Online: wachten of melden. Bij AFAS: check je data en de logboeken.

Wat moet je doen bij een 500?

• Check eerst: is het een bekende storing? Kijk op de statuspagina van de softwareleverancier
• Bij AFAS: check het Profit logboek voor de exacte foutmelding
• Bij Exact Online: probeer het over een paar minuten opnieuw (met exponential backoff), en meld het bij support als het aanhoudt
• Vermijd het tijdvak 04:00-04:30 CET bij Exact Online (onderhoud)

Praktijkvoorbeelden uit verschillende sectoren

Laten we even concreet maken hoe deze fouten er in de praktijk uitzien — in verschillende branches.

Groothandel: 429-fout bij maandafsluiting

Een groothandel met ~500 orders per dag koppelt zijn ordersysteem aan Exact Online. Aan het einde van elke maand draait het systeem een grote batchsynchronisatie van openstaande facturen en backorders. Exact Online gooit de verbinding dicht met een 429 Too Many Requests.

Het probleem: alle 500+ facturen worden in één keer opgevraagd, elk met meerdere API-calls (factuurgegevens, factuurregels, klantgegevens, btw-berekening). Dat zijn al snel 2000+ calls in een paar minuten.

Oplossing: spreiding. In plaats van alles tegelijk, verdeeld over de dag. Of gebruik bulk-endpoints die meerdere facturen in één call ophalen.

Bouwbedrijf: 500-fout bij Bouw7-Exact koppeling

Een installatiebedrijf (~30 medewerkers) heeft een koppeling tussen Bouw7 (projectsoftware) en Exact Online voor uren, facturen en materiaalregistratie. Plots verschijnen er 500-foutmeldingen bij het doorzetten van facturen.

Bij nader onderzoek blijkt: de btw-code voor een specifiek project klopt niet voor het bestemmingsland. Bouw7 stuurt een Nederlandse btw-code, maar het project is in België. Exact Online weigert de factuur met een 500-fout.

Dit is géén serverstoring. Het is een inhoudelijke validatie die faalt. De oplossing: corrigeer de btw-code mapping tussen Bouw7 en Exact Online, zodat per land de juiste code wordt gebruikt.

Retailer met e-commerce: 401-fout na personeelswisseling

Een webshop (b2b groothandel, ~15 medewerkers) koppelt WooCommerce met Exact Online voor automatische factuurverwerking. Na het vertrek van de financieel medewerker stopt de synchronisatie. De foutmelding: 401 Unauthorized.

Het probleem: de OAuth-autorisatie stond op naam van de vertrokken medewerker. Diens account is geblokkeerd in Exact Online. De koppeling heeft geen toegang meer.

Oplossing: heractiveer de verbinding met een account dat blijft bestaan (eigenaar of vaste boekhouder). Lesson learned: zet kritieke autorisaties nooit op naam van tijdelijke medewerkers.

Dienstverlener met AFAS: 400-fout bij verkooporders

Een HR-dienstverlener (~20 medewerkers) stuurt verkooporders via een koppeling naar AFAS Profit. Plotseling stoppen orders met synchroniseren. De fout: HTTP 400.

De oorzaak: iemand heeft in AFAS een nieuw verplicht veld toegevoegd aan verkooporders (bijvoorbeeld een kostenplaats). De koppeling stuurt dat veld niet mee, dus AFAS weigert de order.

Oplossing: pas de koppeling aan zodat het nieuwe verplichte veld wordt meegestuurd, of maak het veld optioneel in AFAS (als dat kan).

Wat moet je doen bij welke fout?

Hier een overzicht van de meest effectieve aanpak per foutcode:

De belangrijkste valkuil: elke fout behandelen alsof het hetzelfde is. Dat is het niet. Een 400 vraagt om een datafix. Een 429 vraagt om geduld. Een 401 vraagt om rechten.

Veelgemaakte fouten die het erger maken

Hier zijn de dingen die ik het vaakst zie misgaan bij klanten die zelf proberen hun koppelingen te debuggen:

Fout 1: Blind opnieuw proberen bij elke foutcode

Veel bedrijven configureren hun koppeling zo dat bij élke fout automatisch opnieuw wordt geprobeerd. Dit werkt averechts. Exact Online heeft dit specifiek benoemd: veel apps blijven oneindig opnieuw proberen na een fout, wat de API onnodig belast (Brixxs FAQ).

Bij een 400-fout heeft opnieuw proberen geen enkele zin. Je stuurt dezelfde foute data opnieuw. Bij een 429 moet je juist wachten. Bij een 500 kan een retry zinvol zijn, maar pas na vertraging.

Fout 2: Koppeling instellen zonder foutafhandeling en monitoring

Een flow die stilletjes faalt zonder dat iemand het merkt, is erger dan geen automatisering. Ik zie dit vaak: een koppeling werkt een jaar prima, dan stopt hij, en niemand ziet het tot de boekhouder belt dat facturen ontbreken.

Bouw altijd foutafhandeling en notificaties in. Als een order niet kan worden doorgezet, moet iemand een e-mail krijgen. Als een factuur faalt, moet die in een foutwachtrij terechtkomen waar je dagelijks naar kijkt.

Fout 3: Token op naam van een medewerker die vertrekt

Een 401-fout ontstaat vaak simpelweg omdat de medewerker op wiens naam de OAuth-autorisatie staat, het bedrijf heeft verlaten of is geblokkeerd. De koppeling werkte jarenlang prima, maar valt ineens stil.

Kies een persoon die langdurig bij de organisatie blijft om de autorisatie te doen. Niet de stagiair. Niet de tijdelijke kracht. De eigenaar of een vaste medewerker.

Fout 4: AFAS 500 verwarren met een echte servercrash

Bij AFAS betekent een 500 meestal NIET dat de server plat ligt. Het is een functionele afkeuring van de data door de bedrijfslogica. Vaak krijg je meldingen als: "Om een afspraak aan te maken dienen er genodigden te zijn."

Check altijd het Profit logboek. Daar staat precies wat er mis is. Het is bijna altijd een ontbrekend veld, een verkeerde waarde, of een bedrijfsregel die niet wordt nageleefd.

Fout 5: Eén API-sleutel voor meerdere systemen

Het gebruik van een enkele API-sleutel over meerdere systemen kan leiden tot onverwachte rate limit-fouten. Omdat alle requests tegen hetzelfde quotum tellen, kan zelfs matig gebruik snel oplopen.

Voorbeeld: je hebt een webshop, een CRM, en een rapportagetool. Alle drie gebruiken hetzelfde Exact Online token. Dat zijn drie systemen die continu calls maken. De 60-calls-per-minuut limiet is zo bereikt.

Oplossing: gebruik waar mogelijk aparte API-tokens per systeem, of bundel calls efficiënter.

Voorkomen is beter dan genezen

Het mooiste is natuurlijk als je deze foutmeldingen helemaal niet krijgt. Of als je ze krijgt, dat je direct weet wat er aan de hand is.

Hier zijn een paar praktische tips:

• Bouw foutafhandeling in vanaf dag 1: Elke koppeling moet weten wat te doen bij een fout. Opnieuw proberen (met vertraging)? Notificatie sturen? In een foutwachtrij zetten?
• Monitor je API-gebruik: Veel systemen hebben dashboards waar je je API-calls kunt zien. Check dit wekelijks. Zit je aan 80% van je limiet? Dan is het tijd om te optimaliseren.
• Gebruik caching waar mogelijk: Vraag niet elke keer dezelfde data op. Sla klantgegevens lokaal op als die toch niet veranderen. Dat scheelt enorm in API-calls.
• Test met testdata eerst: Voor je een koppeling live zet, test hem grondig met testdata. Probeer een order zonder klantnummer. Probeer een factuur met een negatief bedrag. Kijk hoe het systeem reageert.
• Documenteer wie wat mag: Wie heeft de OAuth-autorisatie gedaan? Op wiens naam staat het token? Wat zijn de rechten? Zet dit in een document, zodat het niet verloren gaat als iemand vertrekt.
• Plan onderhoud slim: Als je weet dat Exact Online tussen 04:00-04:30 onderhoud doet, plan je grote synchronisaties dan niet op dat moment.

En misschien wel het belangrijkste: zorg dat je begrijpt wat je koppeling doet. Je hoeft geen developer te zijn, maar je moet wel weten: welke systemen praten met elkaar, hoe vaak, en wat er gebeurt als het misgaat.

Veel MKB-bedrijven hebben koppelingen die niemand meer snapt. De developer die het heeft gebouwd is weg. De documentatie bestaat niet. En als het misgaat, staat iedereen met de mond vol tanden.

Dat kan anders. Een goed gebouwde systeemintegratie heeft duidelijke documentatie, foutafhandeling, en iemand die weet hoe het werkt. Dat hoeft geen fulltime developer te zijn. Maar er moet wel iemand zijn die de telefoon kan pakken als het nodig is.

Veelgestelde vragen

Wat betekent een 400-fout bij een API-koppeling?

Een 400-fout (Bad Request) betekent dat je request niet klopt. Meestal ontbreekt een verplicht veld, of je stuurt een verkeerd datatype (tekst in plaats van een getal). Check de foutmelding zelf — die vertelt vaak precies wat er mis is.

Waarom krijg ik steeds een 401-fout in mijn Exact Online koppeling?

Een 401-fout betekent dat je geen toegang hebt. Vaak is dit omdat een OAuth-token is verlopen, of omdat de gebruiker op wiens naam de koppeling staat is geblokkeerd of geen rechten meer heeft. Controleer de autorisatie en hernieuw het token.

Hoe voorkom ik een 429-fout bij Exact Online?

Exact Online heeft een limiet van 60 calls per minuut en 50.000 per dag (binnenkort verlaagd naar 5.000). Voorkom een 429-fout door: minder vaak te pollen, meer data in één call op te halen, caching te gebruiken, en piekuren te vermijden. Spreiding over de dag helpt enorm.

Betekent een 500-fout altijd dat de server plat ligt?

Niet altijd. Bij Exact Online is een 500 meestal een echte serverstoring of bug. Bij AFAS daarentegen betekent een 500 vaak een inhoudelijke fout in je data (verplicht veld ontbreekt, btw-code klopt niet). Check het Profit logboek bij AFAS om de exacte oorzaak te zien.

Heeft het zin om een gefaalde API-call automatisch opnieuw te proberen?

Dat hangt af van de foutcode. Bij een 400 niet — je stuurt dezelfde foute data opnieuw. Bij een 429 wel, maar wacht eerst (exponential backoff: 1s, 2s, 4s). Bij een 500 kan het zinvol zijn, maar pas na vertraging. Bij een 401 moet je eerst de autorisatie fixen.

Hoe weet ik of mijn koppeling te veel API-calls maakt?

Veel systemen hebben dashboards waar je je API-gebruik kunt zien. Bij Exact Online kun je dit checken via je account. Als je regelmatig 429-fouten krijgt, of als je dicht bij je daglimiet zit, is het tijd om te optimaliseren: minder vaak pollen, meer data per call ophalen, caching gebruiken.

Wat moet ik doen als ik een foutmelding krijg die ik niet snap?

Kopieer de volledige foutmelding (inclusief error code en message). Google de foutmelding samen met de naam van het systeem (bijv. "AFAS 500 error Om een afspraak aan te maken"). Vaak vind je binnen 5 minuten iemand anders die hetzelfde probleem had. Als dat niet helpt, neem contact op met de support van je softwareleverancier — of met degene die je koppeling heeft gebouwd.

Tijd om grip te krijgen op je koppelingen

Foutmeldingen zijn niet eng. Ze zijn gewoon communicatie. Het systeem vertelt je wat er mis is. De vraag is of je de taal spreekt.

400: jij stuurt iets fout. 401: je mag hier niet binnen. 429: je bent te enthousiast. 500: hun kant (of bij AFAS: jouw data klopt inhoudelijk niet).

Als je deze codes herkent en begrijpt, kun je 80% van de koppelingsproblemen zelf oplossen. Of in ieder geval weten wanneer je wel of niet in paniek moet raken.

Het MKB worstelt enorm met automatisering. Maar liefst 94% vindt zichzelf onvoldoende geautomatiseerd. En een groot deel van die frustratie komt doordat koppelingen onduidelijk zijn. Ze werken, tot ze niet meer werken. En dan weet niemand waarom.

Dat kan anders. Met een beetje begrip van wat die foutcodes betekenen, met goede foutafhandeling, en met iemand die weet hoe je systemen werken, kun je een stuk rustiger slapen.

Heb je een koppeling die regelmatig vastloopt? Of wil je een nieuwe integratie opzetten maar weet je niet waar te beginnen? Plan een adviesgesprek. We kijken samen naar je situatie en vertellen eerlijk of je iets nodig hebt — en zo ja, wat.