KVK API-fouten en retries: wat wel en niet opnieuw proberen
Een 429 is geen 404 en een 502 is geen 400. Zo bepaal je welke KVK API-fouten je opnieuw probeert, welke je toont en hoe je backoff bouwt zonder tokens te verspillen.
Je checkout werkt prima in de test. Dan, op een drukke maandagochtend, krijgen een paar klanten “Er ging iets mis” te zien terwijl ze hun KVK-nummer invullen. In de logs staat een mix van 404’s, één 429 en een paar 502’s, en je code behandelde ze allemaal hetzelfde: drie keer opnieuw proberen en dan opgeven. Een deel van die retries was zinloos, een deel was schadelijk en één fout had de klant nooit mogen bereiken.
Goede foutafhandeling bij bedrijfsopzoekingen draait om één vraag per fout: verandert het resultaat als ik het nog een keer probeer? In dit artikel lopen we door de fouten die de KVKBase API teruggeeft, delen we ze in bij “opnieuw proberen”, “repareren” en “aan de gebruiker vertellen”, en laten we een stukje code zien dat dit consequent doet.
De drie soorten fouten
Elke foutmelding van de API heeft dezelfde vorm: een HTTP-status plus een body met een machineleesbare code en een leesbare message. De volledige lijst staat in de foutcodes-documentatie, maar in de praktijk deel je ze in drie groepen in.
De eerste groep gaat over jouw invoer: INVALID_KVK_NUMBER, INVALID_VAT_NUMBER, INVALID_QUERY en INVALID_REQUEST, allemaal status 400. Opnieuw proberen heeft geen zin, want hetzelfde verzoek faalt elke keer op dezelfde manier. De juiste reactie is de invoer herstellen of de gebruiker vertellen wat er niet klopt. Een KVK-nummer dat geen 8 cijfers is, is het klassieke voorbeeld: controleer het vóór je de API aanroept met de regels voor formaat en checksum, dan komen de meeste van deze fouten nooit voor.
De tweede groep is “het antwoord is nee”: NOT_FOUND met status 404. Dat is een geldig antwoord, geen storing. Het bedrijf bestaat niet, is nooit ingeschreven of je hebt een typfout die toevallig 8 cijfers lang is. Probeer dit niet opnieuw. Toon een vriendelijke melding als “we vonden dit bedrijf niet, controleer het nummer” en laat de gebruiker het corrigeren.
De derde groep is tijdelijke problemen: RATE_LIMIT_EXCEEDED (429), UPSTREAM_ERROR (502), UPSTREAM_BUDGET (503) en de zeldzame INTERNAL_ERROR (500). Hier kan wachten en opnieuw proberen wel helpen.
Rate limits: houd je aan Retry-After
Een 429 met RATE_LIMIT_EXCEEDED betekent dat je in de huidige minuut te veel verzoeken hebt gestuurd voor je abonnement. Het antwoord bevat een Retry-After-header met het aantal seconden tot het venster reset. Gebruik die. Een vaste pauze van één seconde is in beide richtingen fout: te kort als het venster nog 40 seconden duurt en verspillend als het er nog één heeft.
Succesvolle antwoorden hebben ook X-RateLimit-Limit en X-RateLimit-Remaining. Bij bulkklussen lees je het resterende aantal en rem je af voordat je op nul komt, in plaats van tegen de limiet aan te botsen en je daarna te herstellen. Voor grote imports past het batch-endpoint beter dan duizend losse calls.
Er is nog een tweede 429 die er hetzelfde uitziet maar het niet is: QUOTA_EXCEEDED. Dan is het maandelijkse tokentegoed op en helpt een minuut wachten niet. Kijk dus altijd naar de code, niet alleen naar de status. Behandel QUOTA_EXCEEDED als een alarm voor je team (upgraden of de klus pauzeren) en nooit als iets wat je in een lus opnieuw probeert. Maak je je zorgen over tokens, lees dan hoe je KVK API-kosten verlaagt door per klus de goedkoopste call te kiezen.
Upstream-fouten: retry met backoff en jitter
Een 502 UPSTREAM_ERROR betekent dat een dienst achter ons, zoals het KVK-register of VIES voor btw-controles, niet antwoordt. Dat is meestal van korte duur. Probeer na een korte pauze opnieuw, verdubbel de pauze bij elke poging en voeg wat willekeur toe, zodat honderd workers niet allemaal op dezelfde seconde terugkomen.
Een 503 UPSTREAM_BUDGET hoort bij Belgische data wanneer het dagbudget voor data op is en het bedrijf nog niet is opgeslagen. Het antwoord bevat een Retry-After-header en die kan vele minuten zijn. Een snelle retry-lus heeft hier geen zin: volg de header, of zet de opzoeking in een wachtrij en ga door met de rest van je klus.
Twee grenzen houden een retrystrategie eerlijk. Begrens het aantal pogingen (drie tot vijf is ruim genoeg voor een verzoek dat een gebruiker afwacht) en begrens de totale tijd. Een klant wacht geen 30 seconden tot een bedrijfsnaam in een formulier verschijnt. Faal bij interactieve flows snel en bied een alternatief: laat de gebruiker de bedrijfsgegevens zelf invullen en controleer ze achteraf op de achtergrond.
Een kleine retry-wrapper
Hier is een compacte TypeScript-helper die deze regels volgt. Hij probeert alleen opnieuw bij 429 met de rate-limit-code, 502, 503 en 500, houdt zich aan Retry-After en geeft al het andere meteen terug.
const RETRYABLE = new Set(["RATE_LIMIT_EXCEEDED", "UPSTREAM_ERROR", "UPSTREAM_BUDGET", "INTERNAL_ERROR"]);
export async function kvkFetch(path: string, maxAttempts = 4) {
for (let attempt = 1; ; attempt++) {
const res = await fetch(`https://api.kvkbase.nl${path}`, {
headers: { Authorization: `Bearer ${process.env.KVKBASE_API_KEY}` },
});
if (res.ok) return res.json();
const { error } = await res.json();
const retryable = RETRYABLE.has(error.code);
if (!retryable || attempt >= maxAttempts) {
throw Object.assign(new Error(error.message), { code: error.code, status: res.status });
}
const header = Number(res.headers.get("Retry-After"));
const backoff = 2 ** attempt * 250 + Math.random() * 250;
const waitMs = header > 0 ? Math.min(header, 30) * 1000 : backoff;
await new Promise((r) => setTimeout(r, waitMs));
}
}
De aanroeper schakelt dan op error.code: een melding bij NOT_FOUND, een formulierfout bij de 400-codes en een intern alarm bij UNAUTHORIZED en QUOTA_EXCEEDED. Let op de grens van 30 seconden op Retry-After: vraagt de header om meer, geef dan nu op en zet de klus in een wachtrij in plaats van een verzoek te blokkeren.
Maak fouten zichtbaar
Retries verbergen problemen als je er nooit naar kijkt. Log de foutcode, het pogingnummer en het request-ID uit de response-headers, en tel hoe vaak elke code voorkomt. Een plotselinge stijging van 429’s betekent dat je een throttle of een groter abonnement nodig hebt, een stijging van 502’s is een blik op het health-endpoint waard en één enkele UNAUTHORIZED in productie wijst meestal op een geroteerde sleutel.
Gebruik ook aparte sleutels: een kvk_test_-sleutel in ontwikkeling en een kvk_live_-sleutel in productie, zodat testverkeer nooit je echte tegoed opeet.
Probeer het met je eigen integratie
Pak de drie meest voorkomende fouten uit je logs van vandaag en controleer of elk de juiste tak neemt: opnieuw proberen, repareren of de gebruiker informeren. Heb je nog geen KVKBase API-sleutel, dan kun je een account aanmaken op kvkbase.nl en deze gevallen met echte antwoorden uitproberen in een paar minuten.