Elke fout, uitgelegd op een stabiel adres.
Deze pagina is een operationele referentie, geen verkooppraatje. Elke foutklasse van de Connect-API heeft hier een permanent anker; de foutantwoorden van de API zullen naar deze adressen verwijzen. U krijgt de waarschijnlijke oorzaak en de oplossing — in die volgorde. Terug naar de ontwikkelaarsdocumentatie.
Sleutel ontbreekt, misvormd of onbekend
De API authenticeert uitsluitend via de header Authorization: Bearer vgk_… — nooit via een sessiecookie. Een ingetrokken sleutel wordt onbekend op het moment van de intrekking.
De oplossing. Controleer dat de header werkelijk vertrekt (proxy's strippen hem soms), dat de sleutel met vgk_ begint en dat hij niet vanuit de console van het kantoor is ingetrokken. Omdat het geheim alleen bij de aanmaak wordt getoond, wordt een verloren sleutel vervangen, niet teruggehaald.
Verlopen sleutel
Elke sleutel verloopt één jaar na de aanmaak — de datum expire_le is vanaf dag één zichtbaar in de console van het kantoor. De 401 bij verval is expliciet: hij zegt dat de sleutel bestond en niet langer geldig is.
De oplossing. Maak een nieuwe sleutel aan, schakel uw aanroepen over, trek de oude in. Plan deze vervanging in uw operations in plaats van haar te ontdekken: de datum is een jaar op voorhand bekend.
Onvoldoende scope
Sleutels dragen lecture (lezen, de standaard) en/of ecriture (schrijven). Een gebeurtenis kwalificeren vereist ecriture; een alleen-lezensleutel krijgt een 403, ongeacht de resource.
De oplossing. Maak een sleutel aan met de benodigde scope — en alleen die. Least privilege is bewust: een integratie die alleen leest, heeft geen reden om een schrijfsleutel te bezitten.
Niet gevonden — of van een ander kantoor
Een 404 betekent dat de resource niet bestaat of aan een ander kantoor toebehoort. De API maakt nooit onderscheid tussen de twee gevallen: onderscheiden zou onthullen wat elders bestaat. De afscheiding wordt afgedwongen op databaseniveau, niet alleen in applicatiecode.
De oplossing. Controleer de seq tegen het journaal van het kantoor waartoe de sleutel behoort (GET /api/v1/evenements). Integreert u meerdere kantoren, dan heeft elk kantoor zijn eigen sleutels: een seq reist niet tussen kantoren.
Limiet overschreden
60 verzoeken per minuut per sleutel, standaard (per sleutel aanpasbaar). Het antwoord draagt Retry-After en de headers X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.
De oplossing. Respecteer Retry-After — geen onmiddellijke retry. De limiet raken tijdens het pollen is bijna altijd het teken van een volledige herlezing: de cursor depuisSeq herleest nooit wat al gelezen is.
De handtekening klopt niet aan uw kant
Uw ontvanger moet v1 = HMAC-SHA256(secret, t + "." + body) herberekenen op basis van de ruwe body zoals ontvangen, en elke t ouder dan 5 min verwerpen. De klassieke missers: de body opnieuw geserialiseerd vóór de verificatie (geherformatteerde JSON heeft niet meer dezelfde bytes), een klok die voorbij de tolerantie afdrijft, en een genegeerde rotatie — gedurende 24 u draagt de header één v1 per nog geldig geheim, en u moet aanvaarden zodra er één overeenstemt.
De oplossing. Verifieer tegen de ruwe bytes, synchroniseer uw klok (NTP), test uw verificatie tijdens een rotatie. De Node- en Python-snippets in de documentatie doen precies dit — kopieer ze in plaats van ze te herschrijven.
Een gebeurtenis komt twee keer aan
De bezorging is at-least-once, in batches van hoogstens 100, in journaalvolgorde; de cursor schuift alleen op bij uw 2xx, batch per batch. Een storing na ontvangst maar vóór het opschuiven van de cursor veroorzaakt een herbezorging — dat is het contract, geen defect.
De oplossing. De seq is uw idempotentiesleutel: verwerk elke sequentie precies één keer, en antwoord pas 2xx na het persisteren. Een te vroege 2xx gevolgd door een crash is de enige manier om een gebeurtenis te verliezen.
Het journaal lijkt onvolledig of herhaalt zich
depuisSeq is strikt exclusief: alleen gebeurtenissen met een hogere seq worden teruggegeven, oplopend gesorteerd, hoogstens 500 per pagina. Het antwoord geeft prochainSeq terug, om ongewijzigd terug te sturen. Een pagina korter dan limite betekent het einde van het journaal.
De oplossing. Persisteer prochainSeq tussen runs en herbereken hem nooit zelf. Duplicaten betekenen dat u bent herstart vanaf een te oude cursor; gaten betekenen dat u een mislukte pagina hebt overgeslagen zonder haar opnieuw af te spelen.
Parameter buiten het schema
Een onbekende status, een dispositie buiten de lijst (planifie, traite, ecarte), een niet-gehele limite: het antwoord benoemt het betrokken veld, en niets anders — foutmeldingen dragen nooit dossierinhoud.
De oplossing. De OpenAPI-specificatie is de bron: de enumeraties en grenzen die zij declareert, zijn die welke de server afdwingt, aangezien zij door de server wordt geserveerd.
Onvoldoende scope (resource-API)
De resource-endpoints (/clients, /dossiers, documenten, screening, alerts) vereisen een fijnmazige scope: clients:*, dossiers:*, pieces:*, criblage:* of de specifieke scope alertes:qualifier. Een legacy-sleutel lecture verleent elke scope *:lecture en ecriture elke *:ecriture — maar alertes:qualifier wordt nooit overgeërfd: een alert kwalificeren is een handeling van de verantwoordelijke, gedelegeerd door die scope aan te vinken bij de aanmaak van de sleutel.
De oplossing. Maak een sleutel aan met precies de scopes die uw integratie nodig heeft — en alleen die. De detail van het antwoord benoemt de ontbrekende scope.
Resource niet gevonden — of van een ander kantoor
Dezelfde regel als #cloisonnement, toegepast op resources: een cliënt, een dossier, een document of een alert die niet bestaat of aan een ander kantoor toebehoort, krijgt dezelfde 404. De API houdt de twee gevallen nooit uit elkaar.
De oplossing. Controleer de identifier tegen de lijsten van het kantoor waartoe de sleutel behoort. Een identifier reist nooit van het ene kantoor naar het andere.
Header Idempotency-Key ontbreekt
Elke POST die iets aanmaakt of in gang zet (cliënt, dossier, document, screening, uiteindelijk begunstigden) vereist de header Idempotency-Key: een stabiele tekenreeks van hoogstens 200 tekens, één per operatie. Dezelfde sleutel met dezelfde body opnieuw afspelen geeft hetzelfde antwoord terug, zonder effect — uw bescherming tegen duplicaten bij een netwerkincident.
De oplossing. Genereer de sleutel vóór de eerste poging (één UUID per bedrijfsoperatie) en hergebruik hem ongewijzigd bij elke retry van diezelfde operatie.
Idempotentiesleutel hergebruikt met een andere body
Deze Idempotency-Key is in de afgelopen 24 uur al gebruikt voor een andere body. De sleutel speelt een antwoord opnieuw af, hij overschrijft er nooit een: hem hergebruiken voor een nieuwe operatie is bijna altijd het teken van een sleutel afgeleid van een teller of een afgekapte datum.
De oplossing. Een nieuwe sleutel voor elke nieuwe operatie. Leid de sleutel nooit af van gegevens die zich over operaties heen herhalen.
Verzegeld dossier: het register ligt vast
De verzegeling legt de integriteitsketen van het dossier vast — dat is de bewijswaarde ervan. Een verzegeld dossier kan niet meer worden bewerkt, ontvangt geen documenten meer en wordt via dit kanaal niet meer hergescreend. Alleen het kwalificeren van alerts blijft mogelijk: dat wordt off-chain geschreven, de verzegelde kop beweegt nooit.
De oplossing. Niets te "corrigeren": dit is bewuste onveranderlijkheid. Moeten er gegevens veranderen, dan is dat een nieuwe waakzaamheidsoperatie in de applicatie, geen mutatie van het verzegelde dossier.
Documentformaat niet aanvaard
Bewijsstukken aanvaarden PDF, JPG, JPEG, PNG en WEBP — dezelfde formaten als de applicatie. De controle gebeurt op de extensie van de verplichte filename: een document zonder geldige bestandsnaam wordt geweigerd, ongeacht de inhoud.
De oplossing. Converteer vóór het verzenden (een TIFF- of HEIC-scan laat zich omzetten naar PDF of JPEG) en stuur de inhoud als standaard base64 in contenu, met een type uit de stabiele a_doc_*-codes.
Document groter dan 6 MB
De limiet geldt voor het gedecodeerde bestand (6 MB), dezelfde als in de applicatie en het aanleverportaal. Omdat base64 een derde aan encoderingsoverhead toevoegt, aanvaardt de request-body tot 9 MB.
De oplossing. Comprimeer het document (een in kleur op 300 dpi gescande pdf zakt in grijswaarden bijna altijd onder de limiet) in plaats van het op te splitsen.
Screeningbron niet beschikbaar
Geen enkele entiteit van het dossier kon tegen de lijsten worden gecontroleerd: de bron (index van officiële lijsten of provider) antwoordde niet. De API weigert te concluderen — een "schoon" rapport bovenop een dode bron zou het slechtst denkbare vals-negatief zijn. De storing wordt op het dossier geregistreerd (erreurSource). Een gedeeltelijke uitval produceert deze 502 niet: het 200-antwoord behoudt de treffers van de entiteiten die wél antwoordden en benoemt de mislukte in erreurSourceEntites.
De oplossing. Speel dezelfde aanroep later opnieuw af, met dezelfde Idempotency-Key: alleen succesantwoorden worden door de idempotentie onthouden — opnieuw afspelen na een fout voert een echte screening uit.
Deze pagina zal met de API mee evolueren; de bestaande ankers veranderen echter nooit van adres — u kunt ze opslaan in uw operationele logs.