Varje fel, förklarat på en stabil adress.
Den här sidan är en driftreferens, inte en säljpitch. Varje felklass i Connect-API:t har ett permanent ankare här; API:ts felsvar kommer att peka på dessa adresser. Du får den troliga orsaken och åtgärden — i den ordningen. Tillbaka till utvecklardokumentationen.
Nyckel saknas, är felformad eller okänd
API:t autentiserar uteslutande via huvudet Authorization: Bearer vgk_… — aldrig via en sessionskaka. En återkallad nyckel blir okänd i samma ögonblick som den återkallas.
Åtgärden. Kontrollera att huvudet verkligen skickas iväg (proxyer tar ibland bort det), att nyckeln börjar med vgk_ och att den inte har återkallats från byråns konsol. Eftersom hemligheten bara visas vid skapandet ersätts en förlorad nyckel — den återställs inte.
Utgången nyckel
Varje nyckel går ut ett år efter skapandet — datumet expire_le syns i byråns konsol från första dagen. Utgångens 401 är uttrycklig: den säger att nyckeln har funnits och inte längre är giltig.
Åtgärden. Skapa en ny nyckel, styr över dina anrop, återkalla den gamla. Planera in bytet i din drift i stället för att upptäcka det: datumet är känt ett år i förväg.
Otillräckligt scope
Nycklar bär lecture (läsning, standard) och/eller ecriture (skrivning). Att kvalificera en händelse kräver ecriture; en läsnyckel får 403 oavsett resurs.
Åtgärden. Skapa en nyckel som bär det scope som behövs — och bara det. Minsta möjliga behörighet är avsiktlig: en integration som bara läser har ingen anledning att hålla en skrivnyckel.
Hittas inte — eller tillhör en annan byrå
En 404 betyder att resursen inte finns eller tillhör en annan byrå. API:t skiljer aldrig på de två fallen: att skilja dem åt vore att avslöja vad som finns någon annanstans. Isoleringen upprätthålls på databasnivå, inte bara i applikationskoden.
Åtgärden. Kontrollera seq mot journalen för den byrå nyckeln tillhör (GET /api/v1/evenements). Integrerar du flera byråer har varje byrå sina egna nycklar: en seq reser inte mellan byråer.
Anropstakten överskriden
60 anrop per minut och nyckel, som standard (kan justeras per nyckel). Svaret bär Retry-After och huvudena X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.
Åtgärden. Respektera Retry-After — inget omedelbart nytt försök. Att slå i taket under pollning är nästan alltid tecknet på en fullständig omläsning: markören depuisSeq läser aldrig om det som redan har lästs.
Signaturen går inte att verifiera på din sida
Din mottagare måste räkna om v1 = HMAC-SHA256(secret, t + "." + body) från den råa kropp som togs emot, och avvisa varje t äldre än 5 min. De klassiska missarna: kroppen omserialiserad före verifieringen (omformaterad JSON har inte längre samma bytes), en klocka som driver bortom toleransen, och en ignorerad rotation — i 24 h bär huvudet ett v1 per ännu giltig hemlighet, och du ska acceptera om någon stämmer.
Åtgärden. Verifiera mot de råa bytesen, synka din klocka (NTP), testa din verifiering under en rotation. Node- och Python-exemplen i dokumentationen gör exakt detta — kopiera dem hellre än att skriva om dem.
En händelse kommer två gånger
Leveransen är at-least-once, i omgångar om högst 100, i journalordning; markören flyttas bara fram vid din 2xx, omgång för omgång. Ett fel efter mottagandet men innan markören flyttats fram orsakar en omleverans — det är kontraktet, inte en defekt.
Åtgärden. seq är din idempotensnyckel: behandla varje sekvens exakt en gång, och svara 2xx först efter att du har persisterat. En för tidig 2xx följd av en krasch är det enda sättet att förlora en händelse.
Journalen verkar ofullständig eller upprepar sig
depuisSeq är strikt exklusiv: bara händelser med högre seq returneras, sorterade stigande, högst 500 per sida. Svaret returnerar prochainSeq, som skickas tillbaka oförändrad. En sida kortare än limite betyder journalens slut.
Åtgärden. Persistera prochainSeq mellan körningar och räkna aldrig om den själv. Dubbletter betyder att du startade om från en för gammal markör; luckor betyder att du hoppade över en misslyckad sida utan att spela om den.
Parameter utanför schemat
En okänd status, en disposition utanför listan (planifie, traite, ecarte), en limite som inte är ett heltal: svaret namnger det felande fältet, och inget annat — felmeddelanden bär aldrig ärendeinnehåll.
Åtgärden. OpenAPI-specifikationen är källan: de uppräkningar och gränser den deklarerar är de som servern upprätthåller, eftersom den serveras av just den.
Otillräckligt scope (resurs-API)
Resursändpunkterna (/clients, /dossiers, handlingar, screening, larm) kräver ett finkornigt scope: clients:*, dossiers:*, pieces:*, criblage:* eller det dedikerade scopet alertes:qualifier. En äldre lecture-nyckel ger varje *:lecture-scope och ecriture varje *:ecriture — men alertes:qualifier ärvs aldrig: att kvalificera ett larm är en handling som tillkommer den ansvarige, delegerad genom att det scopet bockas i när nyckeln skapas.
Åtgärden. Skapa en nyckel som bär exakt de scope din integration behöver — och bara dem. Svarets detail namnger det scope som saknas.
Resursen hittas inte — eller tillhör en annan byrå
Samma regel som #cloisonnement, tillämpad på resurser: en kund, ett ärende, en handling eller ett larm som inte finns eller som tillhör en annan byrå får samma 404. API:t skiljer aldrig de två fallen åt.
Åtgärden. Kontrollera identifieraren mot listningarna för den byrå nyckeln tillhör. En identifierare reser aldrig från en byrå till en annan.
Huvudet Idempotency-Key saknas
Varje POST som skapar eller utlöser något (kund, ärende, handling, screening, verkliga huvudmän) kräver huvudet Idempotency-Key: en stabil sträng om högst 200 tecken, en per operation. Att spela om samma nyckel med samma kropp returnerar samma svar, utan effekt — ditt skydd mot dubbletter vid en nätverksincident.
Åtgärden. Generera nyckeln före det första försöket (ett UUID per affärsoperation) och återanvänd den oförändrad vid varje nytt försök av samma operation.
Idempotensnyckel återanvänd med en annan kropp
Denna Idempotency-Key har redan använts för en annan kropp under de senaste 24 timmarna. Nyckeln spelar upp ett svar igen, den skriver aldrig över ett: att återanvända den för en ny operation är nästan alltid tecknet på en nyckel härledd ur en räknare eller ett trunkerat datum.
Åtgärden. En ny nyckel för varje ny operation. Härled aldrig nyckeln ur data som upprepas mellan operationer.
Förseglat ärende: registret är fryst
Förseglingen fryser ärendets integritetskedja — det är dess bevisvärde. Ett förseglat ärende kan inte längre redigeras, tar inte längre emot handlingar och omscreenas inte längre via denna kanal. Bara kvalificering av larm förblir möjlig: den skrivs off-chain, det förseglade kedjehuvudet rör sig aldrig.
Åtgärden. Inget att ”rätta”: detta är avsiktlig oföränderlighet. Måste data ändras är det en ny vaksamhetsåtgärd i applikationen, inte en mutation av det förseglade ärendet.
Handlingens format godtas inte
Styrkande handlingar godtar PDF, JPG, JPEG, PNG och WEBP — samma format som i applikationen. Kontrollen görs på filändelsen i det obligatoriska filename: en handling utan giltigt filnamn avvisas, oavsett innehåll.
Åtgärden. Konvertera före sändning (en TIFF- eller HEIC-skanning konverteras till PDF eller JPEG) och skicka innehållet som standard-base64 i contenu, med en type bland de stabila a_doc_*-koderna.
Handling över 6 MB
Gränsen gäller den avkodade filen (6 MB), samma som i applikationen och insamlingsportalen. Eftersom base64 lägger på en tredjedel i kodningsoverhead godtar anropskroppen upp till 9 MB.
Åtgärden. Komprimera handlingen (en skannad PDF i färg och 300 dpi hamnar nästan alltid under gränsen i gråskala) hellre än att dela upp den.
Screeningkällan otillgänglig
Ingen av ärendets entiteter kunde kontrolleras mot listorna: källan (indexet över officiella listor eller leverantören) svarade inte. API:t vägrar dra en slutsats — en ”ren” rapport ovanpå en död källa vore det värsta tänkbara falska negativa resultatet. Felet registreras på ärendet (erreurSource). Ett partiellt avbrott ger inte denna 502: 200-svaret behåller träffarna för de entiteter som svarade och namnger dem som misslyckades i erreurSourceEntites.
Åtgärden. Spela om samma anrop senare, med samma Idempotency-Key: bara framgångssvar memoreras av idempotensen — att spela om efter ett fel kör en verklig screening.
Den här sidan kommer att utvecklas med API:t; de befintliga ankarna byter dock aldrig adress — du kan lagra dem i dina driftloggar.