Hver fejl, forklaret på en stabil adresse.
Denne side er en driftsreference, ikke en salgstale. Hver fejlklasse i Connect-API'et har et permanent anker her; API'ets fejlsvar vil pege på disse adresser. De får den sandsynlige årsag og løsningen — i den rækkefølge. Tilbage til udviklerdokumentationen.
Manglende, fejlformateret eller ukendt nøgle
API'et autentificerer udelukkende via headeren Authorization: Bearer vgk_… — aldrig via en sessionscookie. En tilbagekaldt nøgle bliver ukendt i samme øjeblik, den tilbagekaldes.
Løsningen. Kontrollér, at headeren faktisk afsendes (proxyer fjerner den undertiden), at nøglen begynder med vgk_, og at den ikke er blevet tilbagekaldt fra kontorets konsol. Da hemmeligheden kun vises ved oprettelsen, erstattes en mistet nøgle — den gendannes ikke.
Udløbet nøgle
Hver nøgle udløber ét år efter oprettelsen — datoen expire_le er synlig i kontorets konsol fra dag ét. Udløbs-401'en er eksplicit: den siger, at nøglen har eksisteret og ikke længere er gyldig.
Løsningen. Opret en ny nøgle, flyt Deres kald over, tilbagekald den gamle. Planlæg denne udskiftning i Deres drift i stedet for at opdage den: datoen kendes et år i forvejen.
Utilstrækkeligt scope
Nøgler bærer lecture (læsning, standard) og/eller ecriture (skrivning). At kvalificere en hændelse kræver ecriture; en nøgle med kun læseadgang modtager en 403, uanset ressourcen.
Løsningen. Opret en nøgle med det nødvendige scope — og kun det. Mindste privilegium er tilsigtet: en integration, der kun læser, har ingen grund til at holde en skrivenøgle.
Findes ikke — eller tilhører et andet kontor
En 404 betyder, at ressourcen ikke findes, eller at den tilhører et andet kontor. API'et skelner aldrig mellem de to tilfælde: at skelne ville afsløre, hvad der findes andetsteds. Isoleringen håndhæves på databaseniveau, ikke kun i applikationskoden.
Løsningen. Kontrollér seq mod journalen for det kontor, nøglen tilhører (GET /api/v1/evenements). Integrerer De flere kontorer, har hvert kontor sine egne nøgler: en seq rejser ikke mellem kontorer.
Rategrænse overskredet
60 forespørgsler i minuttet pr. nøgle, som standard (kan tilpasses pr. nøgle). Svaret bærer Retry-After og headerne X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.
Løsningen. Respektér Retry-After — intet øjeblikkeligt genforsøg. At ramme grænsen under polling er næsten altid tegn på en fuld genindlæsning: depuisSeq-cursoren genlæser aldrig det, der allerede er læst.
Signaturen kan ikke verificeres hos Dem
Deres modtager skal genberegne v1 = HMAC-SHA256(secret, t + "." + body) ud fra den rå body, der er modtaget, og afvise ethvert t ældre end 5 min. De klassiske fejl: en body, der er re-serialiseret før verificeringen (omformateret JSON har ikke længere de samme bytes), et ur, der driver ud over tolerancen, og en ignoreret rotation — i 24 timer bærer headeren én v1 pr. stadig gyldig hemmelighed, og De skal acceptere, hvis blot én matcher.
Løsningen. Verificér mod de rå bytes, synkronisér Deres ur (NTP), test Deres verificering under en rotation. Node- og Python-uddragene i dokumentationen gør præcis dette — kopiér dem frem for at genskrive dem.
En hændelse ankommer to gange
Leveringen er at-least-once, i batches på højst 100, i journalens rækkefølge; cursoren rykker kun frem ved Deres 2xx, batch for batch. En fejl efter modtagelsen, men før cursoren rykker frem, udløser en genlevering — det er kontrakten, ikke en defekt.
Løsningen. seq er Deres idempotensnøgle: behandl hver sekvens præcis én gang, og svar først 2xx efter persistering. En for tidlig 2xx efterfulgt af et nedbrud er den eneste måde at miste en hændelse på.
Journalen virker ufuldstændig eller gentager sig
depuisSeq er strengt eksklusiv: kun hændelser med en højere seq returneres, sorteret stigende, højst 500 pr. side. Svaret returnerer prochainSeq, som sendes tilbage uændret. En side kortere end limite betyder journalens slutning.
Løsningen. Persistér prochainSeq mellem kørsler, og genberegn den aldrig selv. Dubletter betyder, at De er startet forfra fra en for gammel cursor; huller betyder, at De har sprunget en fejlet side over uden at genafspille den.
Parameter uden for skemaet
En ukendt status, en disposition uden for listen (planifie, traite, ecarte), en limite, der ikke er et heltal: svaret nævner det fejlbehæftede felt, og intet andet — fejlbeskeder bærer aldrig sagsindhold.
Løsningen. OpenAPI-specifikationen er kilden: de enumerationer og grænser, den erklærer, er dem, serveren håndhæver, eftersom den serveres af den.
Utilstrækkeligt scope (ressource-API)
Ressource-endpoints (/clients, /dossiers, bilag, screening, advarsler) kræver et finkornet scope: clients:*, dossiers:*, pieces:*, criblage:* eller det dedikerede scope alertes:qualifier. En ældre lecture-nøgle giver alle *:lecture-scopes og ecriture alle *:ecriture — men alertes:qualifier arves aldrig: at kvalificere en advarsel er den ansvarliges handling, delegeret ved at markere dette scope, når nøglen oprettes.
Løsningen. Opret en nøgle med præcis de scopes, Deres integration har brug for — og kun dem. Svarets detail nævner det manglende scope.
Ressource findes ikke — eller tilhører et andet kontor
Samme regel som #cloisonnement, anvendt på ressourcer: en kunde, en sag, et bilag eller en advarsel, der ikke findes, eller som tilhører et andet kontor, får den samme 404. API'et skelner aldrig mellem de to tilfælde.
Løsningen. Kontrollér identifikatoren mod listerne for det kontor, nøglen tilhører. En identifikator rejser aldrig fra ét kontor til et andet.
Headeren Idempotency-Key mangler
Enhver POST, der opretter eller udløser noget (kunde, sag, bilag, screening, reelle ejere), kræver headeren Idempotency-Key: en stabil streng på højst 200 tegn, én pr. operation. At genafspille samme nøgle med samme body returnerer det samme svar, uden effekt — Deres værn mod dubletter ved en netværkshændelse.
Løsningen. Generér nøglen før det første forsøg (én UUID pr. forretningsoperation), og genbrug den uændret ved hvert genforsøg af den samme operation.
Idempotensnøgle genbrugt med en anden body
Denne Idempotency-Key er allerede blevet brugt til en anden body inden for de seneste 24 timer. Nøglen genafspiller et svar, den overskriver aldrig et: at genbruge den til en ny operation er næsten altid tegn på en nøgle afledt af en tæller eller en afkortet dato.
Løsningen. En ny nøgle til hver ny operation. Aflæd aldrig nøglen af data, der gentager sig på tværs af operationer.
Forseglet sag: registeret er fastfrosset
Forseglingen fastfryser sagens integritetskæde — det er dens bevisværdi. En forseglet sag kan ikke længere redigeres, modtager ikke længere bilag og re-screenes ikke længere ad denne kanal. Kun kvalificering af advarsler forbliver mulig: den skrives off-chain, det forseglede hoved flytter sig aldrig.
Løsningen. Intet at "rette": dette er tilsigtet uforanderlighed. Skal data ændres, er det en ny vigilansoperation i applikationen, ikke en mutation af den forseglede sag.
Bilagsformat ikke accepteret
Bilag accepterer PDF, JPG, JPEG, PNG og WEBP — de samme formater som applikationen. Kontrollen sker på filendelsen i det obligatoriske filename: et bilag uden et gyldigt filnavn afvises, uanset dets indhold.
Løsningen. Konvertér før afsendelse (en TIFF- eller HEIC-scanning konverteres til PDF eller JPEG), og send indholdet som standard-base64 i contenu, med en type blandt de stabile a_doc_*-koder.
Bilag over 6 MB
Grænsen gælder den afkodede fil (6 MB), samme som i applikationen og indsamlingsportalen. Da base64 tilføjer en tredjedel i encoding-overhead, accepterer request-body'en op til 9 MB.
Løsningen. Komprimér bilaget (en farvescannet PDF i 300 dpi kommer næsten altid under grænsen i gråtoner) frem for at dele det op.
Screeningkilde utilgængelig
Ingen af sagens enheder kunne kontrolleres mod listerne: kilden (indekset over officielle lister eller leverandøren) svarede ikke. API'et nægter at konkludere — en "ren" rapport oven på en død kilde ville være det værst tænkelige falske negativ. Fejlen registreres på sagen (erreurSource). Et delvist udfald udløser ikke denne 502: 200-svaret beholder matchene for de enheder, der svarede, og nævner de fejlede i erreurSourceEntites.
Løsningen. Genafspil det samme kald senere, med den samme Idempotency-Key: kun succes-svar huskes af idempotensen — en genafspilning efter en fejl udfører en reel screening.
Denne side vil udvikle sig med API'et; de eksisterende ankre skifter dog aldrig adresse — De kan gemme dem i Deres driftslogs.