Elke fout, uitgelegd op een stabiel adres.

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.

Dezelfde 401 draagt "motif": "fin_option_api" wanneer de sleutel is gestopt omdat de API niet meer in het abonnement van het kantoor zit. De datum van die stop is in een e-mail aan de beheerders van het kantoor of, als er geen zijn, aan het factuuradres van het kantoor genoemd en daarna aangekondigd in de header Sunset van elk antwoord op een aanvaarde aanroep (tijdlijn onder #cle-expiree). Zonder motief kan hij ook van een opgeschort abonnement komen: de opschorting sluit de sleutels onmiddellijk af.

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. Bij "motif": "fin_option_api" ligt het niet aan de header en niet aan de sleutel: de beheerder van het kantoor schrijft ons op contact@vigilae.org om de API weer in het abonnement op te nemen, en dezelfde sleutel wordt weer aanvaard zodra dat gebeurd is, tot zijn eigen vervaldatum.

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.

Een API-sleutel kan ook vóór die datum niet langer worden aanvaard, wanneer de API niet meer in het abonnement van het kantoor zit. De stop valt dan ten minste 30 dagen na een eerste e-mail, op de datum die een tweede e-mail noemt, ten minste 7 dagen vooraf verstuurd; beide gaan naar de beheerders van het kantoor of, als er geen zijn, naar het factuuradres van het kantoor. Zodra die vaststaat, is deze datum zichtbaar in de console van het kantoor (veld coupure_le van GET /connect/cles), en elk antwoord op een aanvaarde aanroep kondigt hem aan in de header Sunset tot hij is bereikt. Na die datum krijgt de aanroep de 401 van #authentification, met "motif": "fin_option_api"; zit de API weer in het abonnement, dan wordt de sleutel weer aanvaard, tot zijn eigen vervaldatum.

De oplossing. Maak een nieuwe sleutel aan, schakel uw aanroepen over, trek de oude in. Voor een API-sleutel moet de API dan nog in het abonnement van het kantoor zitten: zonder de API weigert de console er een aan te maken. Plan deze vervanging in uw operations in plaats van haar te ontdekken.

Onvoldoende scope

Sleutels dragen de scopes die bij het aanmaken zijn aangevinkt: de algemene lecture (lezen, de standaard) en ecriture (schrijven), of fijnmazige per resource (clients:lecture, pieces:ecriture, origine-fonds:lecture, journal:lecture…).

De overerving volgt het achtervoegsel, maar één kant op: lecture dekt elke *:lecture, ecriture elke *:ecriture — nooit andersom; een fijnmazige scope opent alleen zichzelf.

Zes scopes vallen buiten dat paar en worden door geen enkele algemene sleutel geërfd: alertes:qualifier, embed:emettre, adversemedia:consulter, conformite:consulter, dispositif:consulter, integrite:consulter. Een gebeurtenis kwalificeren, een embed-token uitgeven, de ongunstige pers bij een dossier of een score voor de dossiervoering lezen volgt nooit uit een algemeen leesrecht: elk wordt apart aangevinkt.

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, en een brede sleutel maakt nooit goed wat een niet expliciet gedelegeerde scope mist.

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.

Dit account bestaat al

Een POST /scim/v2/Users op een userName die voor dit kantoor al is geprovisioneerd, antwoordt met 409 en scimType: uniqueness. De uniciteit wordt gedragen door een databasebeperking, niet door een cache: twee gelijktijdige aanmakingen kunnen geen twee accounts opleveren.

De oplossing. Behandel de 409 als een idempotent succes, niet als een fout: lees het account terug met ?filter=userName eq "…" en ga verder met de teruggegeven identificatie. Een connector die bij een 409 in een lus opnieuw probeert, maakt nooit iets extra's aan.

Dit account valt buiten het bereik van de directory

Een directory kan een account met beheersbevoegdheden van het kantoor niet degraderen en niet deactiveren: het verzoek wordt geweigerd met scimType: mutability en gelogd. Zonder die grens zou een connector die het adres van de compliancefunctionaris overneemt, het kantoor sluiten voor juist degene die ervoor instaat.

De oplossing. Haal die persoon uit het gesynchroniseerde bereik, of wijzig de rol vanuit Vigilae. De weigering geldt alleen dit account: de rest van de partij wordt gewoon toegepast.

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.

Veldwaarde te lang: Nationaliteit

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.

Een andere poging met deze sleutel loopt nog

Twee verzoeken met dezelfde Idempotency-Key kwamen samen aan: het eerste wordt uitgevoerd, het tweede wordt vóór enig effect geweigerd. Juist die weigering voorkomt het duplicaat. Het gangbare geval: een proxy geeft 502 of 504 terwijl de server nog werkt, en uw client speelt het verzoek opnieuw af. De header Retry-After zegt na hoeveel seconden dat kan.

De oplossing. Speel hetzelfde verzoek onveranderd opnieuw af, met dezelfde sleutel, na de aangekondigde wachttijd: u krijgt het antwoord van de eerste poging. Maak nooit een nieuwe sleutel om te "deblokkeren" — dat zou juist het duplicaat maken dat de sleutel voorkomt.

Testomgeving: quotum bereikt

Een testomgeving heeft vaste limieten: 200 cliëntfiches, 50 dossiers en 40 documenten per dossier. Een aanmaking of upload die een ervan zou overschrijden, wordt vóór enige schrijfactie geweigerd, en de weigering zegt welke: de velden ressource, quota en courant bevatten de resource, het plafond en het aantal op het moment van de weigering. Van twee gelijktijdige aanmakingen voor de laatste plaats komt er maar één door. Een bestaande cliëntfiche of een bestaand dossier bewerken verbruikt niets.

De oplossing. Over deze quota valt niet te onderhandelen, en het verzoek opnieuw afspelen levert dezelfde weigering op. Reset de testomgeving vanuit uw werkruimte — ze begint dan opnieuw met de demonstratiegegevens — of sluit een abonnement af: deze quota gelden alleen voor testomgevingen.

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.

Afgesloten dossier: de zakelijke relatie is beëindigd

De relatie is in de applicatie afgesloten: het dossier ontvangt geen schrijfacties meer via de API — geen bewerking, geen document, geen screening, geen uiteindelijk begunstigden. Lezen blijft open: een afgesloten dossier is gedurende de hele bewaartermijn te bekijken en te exporteren.

De oplossing. De relatie heropenen is een menselijke, getraceerde handeling in de applicatie; de API doet het niet voor u. Is de operatie nieuw, open dan een nieuw dossier in plaats van het oude te reanimeren.

Gewist dossier: de gegevens zijn verwijderd

De bewaartermijn is verstreken en de gegevens van het dossier zijn verwijderd. Alleen het auditspoor blijft, dat aantoont dat een dossier heeft bestaan en op de genoemde datum is gewist; het ontvangt geen schrijfactie meer.

De oplossing. Niets te corrigeren en niets opnieuw af te spelen: de wissing is definitief en bewust. Een in uw systemen bewaarde identificatie van een gewist dossier is historie, nooit een doel om naar te schrijven.

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.

Ingebedde widgets niet geactiveerd op deze instantie

De mint POST /api/v1/embed/jetons steunt op de voor uw kantoor opgegeven origins — die lijst stuurt de frame-ancestors-CSP van de ingebedde shell aan. Deze 501 zegt dat de instantie die u aanriep die opslag niet draagt: het embed-oppervlak ligt er door constructie stil, en zegt dat liever dan een token uit te geven dat geen enkele origin ooit zou kunnen tonen. Niet te verwarren met de 400 die wordt teruggegeven aan een kantoor waarvan de origins nog niet zijn opgegeven.

De oplossing. Deze 501 gaat over de instantie, niet over uw aanvraag. Op vigilae.org geeft de beheerder van uw kantoor de origins zelf op, op het scherm "Integraties & beveiliging" (het kader in de widgets-sectie zegt waar); speel daarna dezelfde aanroep opnieuw af. Niets te veranderen in uw code: de aanvraag was goed, de instantie was niet klaar.

Oppervlak niet beschikbaar op deze installatie

Twee basisleesbewerkingen — GET /api/v1/dossiers/{id}/origine-fonds en GET /api/v1/dossiers/{id}/exigences — steunen op opslag die niet elke instantie draagt. Ontbreekt er een, dan zegt de API dat in plaats van een lege lijst te serveren: „niets te melden” en „er is niets gelezen” zijn tegengestelde feiten, en ze verwarren zou een dossier waar niemand naar heeft gekeken laten doorgaan voor een dossier zonder opmerkingen. Deze 501 gaat over de aangeroepen instantie, nooit over uw verzoek of over het dossier.

De oplossing. Herhaal de aanroep niet in een lus: er verandert niets zolang de instantie die opslag niet draagt. Behandel deze code als „gegeven hier niet beschikbaar” en tel hem vooral niet als een nul in uw dashboards — zo wordt een ontbrekende meting een verkeerd cijfer. Op vigilae.org worden beide leesbewerkingen bediend; op een eigen installatie is het opwaarderen van de opslag zaak van uw beheerder.