Varje fel, förklarat på en stabil adress.

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.

Samma 401 bär "motif": "fin_option_api" när nyckeln har stoppats eftersom API:t inte längre ingår i byråns abonnemang. Datumet för stoppet angavs i ett e-postmeddelande till byråns administratörer eller, om sådana saknas, till byråns faktureringsadress, och aviserades sedan i huvudet Sunset i varje svar på ett godtaget anrop (tidsplanen under #cle-expiree). Utan motiv kan det också bero på ett avstängt abonnemang: avstängningen bryter nycklarna omedelbart.

Å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. Med "motif": "fin_option_api" är varken huvudet eller nyckeln orsaken: byråns administratör skriver till oss på contact@vigilae.org för att API:t ska ingå i abonnemanget igen, och samma nyckel godtas igen så snart det är gjort, fram till sitt eget utgångsdatum.

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.

En API-nyckel kan också sluta godtas före detta datum, när API:t inte längre ingår i byråns abonnemang. Stoppet inträffar då minst 30 dagar efter ett första e-postmeddelande, på det datum som ett andra meddelande anger, skickat minst 7 dagar i förväg; båda går till byråns administratörer eller, om sådana saknas, till byråns faktureringsadress. Så snart datumet är fastställt syns det i byråns konsol (fältet coupure_le i GET /connect/cles), och varje svar på ett godtaget anrop aviserar det i huvudet Sunset tills det inträffar. Därefter får anropet den 401 som beskrivs under #authentification, med "motif": "fin_option_api"; ingår API:t i abonnemanget igen godtas nyckeln igen, fram till sitt eget utgångsdatum.

Åtgärden. Skapa en ny nyckel, styr över dina anrop, återkalla den gamla. För en API-nyckel måste API:t fortfarande ingå i byråns abonnemang: utan det vägrar konsolen att skapa en. Planera in bytet i din drift i stället för att upptäcka det.

Otillräckligt scope

Nycklar bär de scope som kryssades i när de skapades: de generella lecture (läsning, standard) och ecriture (skrivning), eller finkorniga per resurs (clients:lecture, pieces:ecriture, origine-fonds:lecture, journal:lecture…).

Arvet följer ändelsen, bara åt ett håll: lecture täcker varje *:lecture, ecriture varje *:ecriture — aldrig tvärtom; ett finkornigt scope öppnar bara sig självt.

Sex scope faller utanför det paret och ärvs från ingen generell nyckel: alertes:qualifier, embed:emettre, adversemedia:consulter, conformite:consulter, dispositif:consulter, integrite:consulter. Att kvalificera en händelse, utfärda en embed-token, läsa ett ärendes ogynnsamma press eller ett omdöme om ärendehanteringen följer aldrig av en generell läsrätt: vart och ett kryssas i för sig.

Å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, och en bred nyckel ersätter aldrig ett scope som inte delegerats uttryckligen.

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.

Detta konto finns redan

En POST /scim/v2/Users på ett userName som redan etablerats för denna byrå svarar 409 med scimType: uniqueness. Entydigheten bärs av ett databasvillkor, inte av en cache: två samtidiga skapanden kan inte ge två konton.

Åtgärden. Behandla 409 som en idempotent framgång, inte som ett fel: läs tillbaka kontot med ?filter=userName eq "…" och fortsätt med den identifierare som returneras. En koppling som gör om försöket i slinga vid en 409 skapar aldrig något mer.

Detta konto ligger utom räckhåll för katalogen

En katalog kan varken nedgradera eller avaktivera ett konto som bär byråns administrationsbefogenheter: begäran avvisas med scimType: mutability och loggas. Utan den gränsen skulle en koppling som övertar den regelansvariges adress stänga ute byrån för just den som svarar för den.

Åtgärden. Ta bort personen ur det synkroniserade omfånget, eller ändra rollen inifrån Vigilae. Avslaget gäller endast detta konto: resten av partiet tillämpas som vanligt.

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.

Fältets värde är för långt: Nationalitet

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.

Ett annat försök med samma nyckel pågår fortfarande

Två anrop med samma Idempotency-Key kom in samtidigt: det första utförs, det andra avvisas före varje verkan. Just detta avvisande hindrar dubbletten. Det vanliga fallet: en proxy svarar 502 eller 504 medan servern fortfarande arbetar, och din klient skickar anropet igen. Huvudet Retry-After anger efter hur många sekunder det kan skickas om.

Åtgärden. Skicka om samma anrop, oförändrat, med samma nyckel, efter den angivna väntetiden: du får svaret från det första försöket. Skapa aldrig en ny nyckel för att ”låsa upp” — det skulle skapa just den dubblett som nyckeln hindrar.

Testmiljö: kvoten är nådd

En testmiljö har fasta gränser: 200 kundposter, 50 ärenden och 40 handlingar per ärende. Ett skapande eller en uppladdning som skulle överskrida någon av dem avvisas före all skrivning, och avvisningen talar om vilken: fälten ressource, quota och courant anger resursen, taket och antalet vid avvisningen. Av två samtidiga skapanden om den sista platsen går bara det ena igenom. Att redigera en befintlig kundpost eller ett befintligt ärende förbrukar ingenting.

Åtgärden. Kvoterna går inte att förhandla om, och att skicka om anropet ger samma avvisning. Återställ testmiljön från din arbetsyta — den börjar då om med demonstrationsdata — eller teckna ett abonnemang: kvoterna gäller bara testmiljöer.

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.

Avslutat ärende: affärsförbindelsen har upphört

Förbindelsen har avslutats i applikationen: ärendet tar inte längre emot skrivningar via API:et — varken redigering, handling, screening eller verkliga huvudmän. Läsningar förblir öppna: ett avslutat ärende kan visas och exporteras under hela bevarandetiden.

Åtgärden. Att återuppta förbindelsen är en mänsklig och loggad handling i applikationen; API:et gör det inte i ditt ställe. Är operationen ny, öppna ett nytt ärende i stället för att återuppliva det gamla.

Gallrat ärende: uppgifterna har raderats

Bevarandetiden har löpt ut och ärendets uppgifter har raderats. Kvar finns bara revisionsspåret, som styrker att ett ärende har funnits och att det gallrades det angivna datumet; det tar inte längre emot någon skrivning.

Åtgärden. Inget att rätta och inget att skicka om: raderingen är slutgiltig och avsiktlig. Ett bevarat id för ett gallrat ärende i dina system är historik, aldrig ett mål för skrivning.

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.

Inbäddade widgetar inte aktiverade på den här instansen

Utfärdandet POST /api/v1/embed/jetons bygger på de ursprung som är angivna för din byrå — den listan är det som styr CSP-direktivet frame-ancestors i det inbäddade skalet. Denna 501 säger att den instans du anropade inte har den lagringen: embed-ytan är där inaktiv genom själva konstruktionen, och den säger det hellre än att utfärda en token som inget ursprung ändå skulle kunna visa. Ska inte förväxlas med den 400 som ges till en byrå vars ursprung ännu inte är angivna.

Åtgärden. Denna 501 handlar om instansen, inte om ditt anrop. På vigilae.org anger administratören för din byrå ursprungen själv, på skärmen ”Integrationer och säkerhet” (rutan i widgetavsnittet säger var); spela sedan om samma anrop. Inget att ändra i din kod: anropet var korrekt, instansen var inte redo.

Ytan är inte tillgänglig i den här installationen

Två grundläggande läsningar — GET /api/v1/dossiers/{id}/origine-fonds och GET /api/v1/dossiers/{id}/exigences — vilar på lagringar som inte varje instans bär. När en saknas säger API:t det i stället för att servera en tom lista: ”inget att anmärka” och ”ingenting lästes” är motsatta fakta, och att blanda ihop dem skulle få ett ärende som ingen har tittat på att framstå som ett ärende utan anmärkning. Denna 501 handlar om den anropade instansen, aldrig om din begäran eller om ärendet.

Åtgärden. Upprepa inte anropet i en loop: ingenting ändras förrän instansen bär den lagringen. Behandla koden som ”uppgift inte tillgänglig här” och räkna den framför allt inte som en nolla i dina instrumentpaneler — det är så en utebliven mätning blir en felaktig siffra. På vigilae.org betjänas båda läsningarna; i en dedikerad installation är uppgraderingen av lagringen din driftsansvariges sak.