Minden hiba, stabil címen elmagyarázva.

Hiányzó, hibás formátumú vagy ismeretlen kulcs

Az API kizárólag az Authorization: Bearer vgk_… fejlécen keresztül hitelesít — munkamenet-sütin keresztül soha. A visszavont kulcs a visszavonás pillanatában ismeretlenné válik.

Ugyanez a 401 tartalmazza a "motif": "fin_option_api" mezőt, ha a kulcsot leállították, mert az API már nem része az iroda előfizetésének. A leállítás dátumát az iroda adminisztrátorainak, ilyenek hiányában az iroda számlázási címére küldött e-mail közölte, majd minden elfogadott hívásra adott válasz Sunset fejléce jelezte (az ütemezés: #cle-expiree). Indok nélkül felfüggesztett előfizetésből is eredhet: a felfüggesztés azonnal megszakítja a kulcsokat.

A teendő. Ellenőrizze, hogy a fejléc valóban elmegy-e (a proxyk néha levágják), hogy a kulcs vgk_ előtaggal kezdődik-e, és hogy nem vonták-e vissza az iroda konzoljából. Mivel a titok csak létrehozáskor látható, az elveszett kulcsot pótolni kell, nem visszanyerni. Ha a válaszban "motif": "fin_option_api" szerepel, sem a fejléc, sem a kulcs nem hibás: az iroda adminisztrátora a contact@vigilae.org címen ír nekünk, hogy az API visszakerüljön az előfizetésbe, és ugyanazt a kulcsot a rendszer ismét elfogadja, amint ez megtörtént, saját lejáratáig.

Lejárt kulcs

Minden kulcs a létrehozása után egy évvel lejár — az expire_le dátum az első naptól látható az iroda konzoljában. A lejárati 401 kifejezett: azt mondja, hogy a kulcs létezett, és már nem érvényes.

Egy API-kulcs elfogadása ennél a dátumnál korábban is megszűnhet, ha az API már nem része az iroda előfizetésének. A leállítás ilyenkor legalább 30 nappal az első e-mail után következik be, azon a napon, amelyet egy legalább 7 nappal előre elküldött második e-mail közöl; mindkettő az iroda adminisztrátorainak, ilyenek hiányában az iroda számlázási címére megy. Amint ez a dátum rögzül, látható az iroda konzoljában (a GET /connect/cles coupure_le mezője), és minden elfogadott hívásra adott válasz jelzi a Sunset fejlécben, amíg el nem érkezik. Ezt követően a hívás az #authentification pontban leírt 401-et kapja, a "motif": "fin_option_api" mezővel; ha az API visszakerül az előfizetésbe, a kulcsot a rendszer ismét elfogadja, saját lejáratáig.

A teendő. Hozzon létre új kulcsot, állítsa át a hívásait, vonja vissza a régit. API-kulcs esetén ehhez az API-nak továbbra is az iroda előfizetésének részét kell képeznie: nélküle a konzol nem enged kulcsot létrehozni. Tervezze be ezt a cserét az üzemeltetésébe, ahelyett hogy meglepetésként érné.

Elégtelen hatókör

A kulcsok a létrehozásukkor bejelölt hatóköröket hordozzák: az általános lecture (olvasás, az alapértelmezés) és ecriture (írás) hatókört, vagy erőforrásonkénti finom hatóköröket (clients:lecture, pieces:ecriture, origine-fonds:lecture, journal:lecture…).

Az öröklés az utótagot követi, csak egy irányba: a lecture lefedi az összes *:lecture, az ecriture az összes *:ecriture hatókört — fordítva soha; egy finom hatókör csak önmagát nyitja meg.

Hat hatókör kilóg ebből a párból, és egyetlen általános kulcsból sem öröklődik: alertes:qualifier, embed:emettre, adversemedia:consulter, conformite:consulter, dispositif:consulter, integrite:consulter. Egy esemény minősítése, beágyazási token kiállítása, egy ügy kedvezőtlen sajtójának vagy ügyviteli pontszámának olvasása soha nem következik általános olvasási jogból: mindegyiket külön kell bejelölni.

A teendő. Hozzon létre a szükséges hatókört — és csakis azt — hordozó kulcsot. A legkisebb jogosultság elve szándékos: a csak olvasó integrációnak semmi oka írási kulcsot tartani, és a tág kulcs sem pótolja azt a hatókört, amelyet nem ruháztak át kifejezetten.

Nem található — vagy egy másik irodáé

A 404 azt jelenti, hogy az erőforrás nem létezik, vagy egy másik irodához tartozik. Az API a két esetet soha nem különbözteti meg: a megkülönböztetés elárulná, mi létezik máshol. Az elkülönítést az adatbázis szintjén kényszerítjük ki, nem csak az alkalmazáskódban.

A teendő. Vesse össze a seq-et annak az irodának a naplójával, amelyhez a kulcs tartozik (GET /api/v1/evenements). Ha több irodát integrál, minden irodának saját kulcsai vannak: a seq nem vándorol irodák között.

Ez a fiók már létezik

Egy POST /scim/v2/Users az ehhez az irodához már kiosztott userName névre 409 választ ad scimType: uniqueness jelöléssel. Az egyediséget adatbázis-megszorítás tartja, nem gyorsítótár: két egyidejű létrehozás nem eredményezhet két fiókot.

A teendő. Kezelje a 409-et idempotens sikerként, ne hibaként: olvassa vissza a fiókot a ?filter=userName eq "…" szűrővel, és folytassa a visszaadott azonosítóval. Az a csatoló, amely 409 után ciklusban próbálkozik, soha nem hoz létre semmi többet.

Ez a fiók a címtár hatókörén kívül esik

A címtár nem fokozhat le és nem tilthat le olyan fiókot, amely az iroda adminisztrációs jogköreit hordozza: a kérés scimType: mutability jelöléssel elutasításra kerül és naplózódik. E korlát nélkül az a csatoló, amely átveszi a megfelelési felelős címét, éppen az elől zárná be az irodát, aki felel érte.

A teendő. Vegye ki ezt a személyt a szinkronizált körből, vagy változtassa meg a szerepkörét a Vigilae-ben. Az elutasítás csak erre a fiókra vonatkozik: a köteg többi része szokásosan érvényesül.

Túllépett sebességkorlát

Kulcsonként 60 kérés percenként, alapértelmezés szerint (kulcsonként felülírható). A válasz Retry-After-t és X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset fejléceket hordoz.

A teendő. Tartsa tiszteletben a Retry-After-t — semmi azonnali újrapróbálkozás. Ha lekérdezés közben ütközik a korlátba, az szinte mindig teljes újraolvasás jele: a depuisSeq kurzor soha nem olvassa újra, amit már olvasott.

Az aláírás nem egyezik az Ön oldalán

A fogadójának a kapott nyers törzsből kell újraszámolnia a v1 = HMAC-SHA256(secret, t + "." + body) értéket, és el kell utasítania minden 5 percnél régebbi t-t. A klasszikus hibák: az ellenőrzés előtt újraszerializált törzs (az újraformázott JSON már nem ugyanazokból a bájtokból áll), a tűrésen túl csúszó óra, és a figyelmen kívül hagyott rotáció — 24 órán át a fejléc minden még érvényes titokhoz egy-egy v1-et hordoz, és el kell fogadnia, ha bármelyik egyezik.

A teendő. A nyers bájtokkal szemben ellenőrizzen, szinkronizálja az óráját (NTP), tesztelje az ellenőrzését rotáció közben. A dokumentáció Node- és Python-részletei pontosan ezt teszik — másolja őket, ne írja újra.

Egy esemény kétszer érkezik meg

A kézbesítés at-least-once, legfeljebb 100-as kötegekben, naplósorrendben; a kurzor csak az Ön 2xx-ére lép tovább, kötegenként. A fogadás utáni, de a kurzor továbblépése előtti hiba újrakézbesítést okoz — ez a szerződés, nem hiba.

A teendő. A seq az Ön idempotenciakulcsa: minden sorszámot pontosan egyszer dolgozzon fel, és csak a tartós mentés után válaszoljon 2xx-szel. Egy korai 2xx és egy azt követő összeomlás az egyetlen mód, ahogy esemény elveszhet.

A napló hiányosnak tűnik vagy ismétli magát

A depuisSeq szigorúan kizáró: csak a nagyobb seq-ű események jönnek vissza, növekvő sorrendben, laponként legfeljebb 500. A válasz visszaadja a prochainSeq értéket, amelyet változatlanul kell visszaadni. A limite-nél rövidebb lap a napló végét jelenti.

A teendő. Őrizze meg a prochainSeq-et a futások között, és soha ne számolja újra saját maga. A duplikátumok azt jelentik, hogy túl régi kurzortól indult újra; a lyukak azt, hogy egy sikertelen lapot újrajátszás nélkül ugrott át.

A sémán kívüli paraméter

Ismeretlen státusz, a listán (planifie, traite, ecarte) kívüli elintézés, nem egész limite: a válasz megnevezi a hibás mezőt, és semmi mást — a hibaüzenetek soha nem hordoznak dossziétartalmat.

A teendő. Az OpenAPI-specifikáció a forrás: az általa deklarált felsorolások és korlátok azok, amelyeket a szerver kikényszerít, hiszen ő maga szolgálja ki.

Túl hosszú értéket tartalmazó mező: Állampolgárság

A válasz megnevezi a hibás mezőt, és semmi mást — a hibaüzenetek soha nem hordoznak dossziétartalmat.

A teendő. Az OpenAPI-specifikáció a forrás: az általa deklarált felsorolások és korlátok azok, amelyeket a szerver kikényszerít, hiszen ő maga szolgálja ki.

Elégtelen hatókör (erőforrás-API)

Az erőforrás-végpontok (/clients, /dossiers, dokumentumok, szűrés, riasztások) finom hatókört igényelnek: clients:*, dossiers:*, pieces:*, criblage:* vagy a dedikált alertes:qualifier hatókört. Egy örökölt lecture kulcs minden *:lecture hatókört megad, az ecriture minden *:ecriture-t — az alertes:qualifier azonban soha nem öröklődik: egy riasztás minősítése a felelős vezető aktusa, amelyet a kulcs létrehozásakor e hatókör bejelölésével lehet delegálni.

A teendő. Hozzon létre pontosan az integrációjához szükséges hatóköröket — és csakis azokat — hordozó kulcsot. A válasz detail mezője megnevezi a hiányzó hatókört.

Az erőforrás nem található — vagy egy másik irodáé

Ugyanaz a szabály, mint a #cloisonnement esetében, erőforrásokra alkalmazva: a nem létező, vagy másik irodához tartozó ügyfél, dosszié, dokumentum vagy riasztás ugyanazt a 404-et kapja. Az API a két esetet soha nem választja szét.

A teendő. Vesse össze az azonosítót annak az irodának a listázásaival, amelyhez a kulcs tartozik. Az azonosító soha nem vándorol egyik irodától a másikig.

Hiányzó Idempotency-Key fejléc

Minden létrehozó vagy műveletindító POST (ügyfél, dosszié, dokumentum, szűrés, tényleges tulajdonosok) megköveteli az Idempotency-Key fejlécet: egy legfeljebb 200 karakteres, stabil karakterláncot, műveletenként egyet. Ugyanazon kulcs újrajátszása ugyanazzal a törzzsel ugyanazt a választ adja vissza, hatás nélkül — ez az Ön védelme a hálózati incidens okozta duplikátumok ellen.

A teendő. A kulcsot az első kísérlet előtt generálja (üzleti műveletenként egy UUID), és ugyanazon művelet minden újrapróbálkozásánál változatlanul használja újra.

Idempotenciakulcs újrahasználva más törzzsel

Ezt az Idempotency-Key-t az elmúlt 24 órában már használták egy másik törzshöz. A kulcs választ játszik újra, soha nem ír felül: új művelethez újrahasználni szinte mindig számlálóból vagy csonkolt dátumból származtatott kulcs jele.

A teendő. Minden új művelethez új kulcs. Soha ne származtassa a kulcsot műveletek között ismétlődő adatból.

Ugyanezzel a kulccsal egy másik kísérlet még fut

Két kérés érkezett együtt ugyanazzal az Idempotency-Key-vel: az első lefut, a második minden hatás előtt elutasításra kerül. Éppen ez az elutasítás akadályozza meg a duplikátumot. A szokásos eset: egy proxy 502-t vagy 504-et ad vissza, miközben a kiszolgáló még dolgozik, és az Ön kliense újra elküldi a kérést. A Retry-After fejléc megadja, hány másodperc múlva ismételje meg.

A teendő. Ismételje meg ugyanazt a kérést változatlanul, ugyanazzal a kulccsal, a jelzett várakozás után: az első kísérlet válaszát kapja meg. Soha ne gyártson új kulcsot a „feloldás” érdekében — épp azt a duplikátumot hozná létre, amelyet a kulcs megelőz.

Tesztkörnyezet: a kvóta betelt

A tesztkörnyezetre rögzített korlátok vonatkoznak: 200 ügyféllap, 50 dosszié és dossziénként 40 dokumentum. Ha egy létrehozás vagy feltöltés bármelyiket túllépné, az API elutasítja, mielőtt bármit is írna, és az elutasítás megmondja, melyik korlátról van szó: a ressource, quota és courant mezők az erőforrást, a felső határt és az elutasítás pillanatában érvényes darabszámot tartalmazzák. Ha két egyidejű létrehozás verseng az utolsó helyért, csak az egyik jut át. Meglévő ügyféllap vagy dosszié módosítása nem terheli a kvótát.

A teendő. Ezek a kvóták nem alku tárgyai, és a kérés megismétlése ugyanazt az elutasítást adja vissza. Állítsa vissza a tesztkörnyezetet az irodafelületéről — ilyenkor a demóadatokkal indul újra —, vagy fizessen elő: ezek a kvóták csak a tesztkörnyezetekre vonatkoznak.

Lezárt dosszié: a nyilvántartás befagyasztva

A lezárás befagyasztja a dosszié integritásláncát — éppen ez adja bizonyító erejét. A lezárt dosszié többé nem szerkeszthető, nem fogad dokumentumot, és ezen a csatornán nem szűrhető újra. Egyedül a riasztások minősítése marad lehetséges: az láncon kívül íródik, a lezárt láncfej soha nem mozdul.

A teendő. Nincs mit „javítani”: ez szándékos megváltoztathatatlanság. Ha adatnak változnia kell, az új átvilágítási művelet az alkalmazásban, nem a lezárt dosszié módosítása.

Megszűnt kapcsolat: a dosszié már nem fogad írást

A kapcsolatot lezárták az alkalmazásban: a dosszié az API-n keresztül már nem fogad írást — sem szerkesztést, sem dokumentumot, sem szűrést, sem tényleges tulajdonosokat. Az olvasás nyitva marad: lezárt dosszié a teljes megőrzési idő alatt megtekinthető és exportálható.

A teendő. A kapcsolat újranyitása emberi, naplózott művelet az alkalmazásban; az API nem teszi meg Ön helyett. Ha a művelet új, nyisson új dossziét, ahelyett hogy a régit élesztené fel.

Törölt dosszié: az adatokat eltávolították

A megőrzési határidő lejárt, és a dosszié adatait törölték. Csak az auditnyom marad, amely tanúsítja, hogy volt egy dosszié, és hogy a megjelölt napon törölték; ez már semmilyen írást nem fogad.

A teendő. Nincs mit javítani és nincs mit megismételni: a törlés végleges és szándékos. A rendszereiben megőrzött, törölt dossziéhoz tartozó azonosító előzmény, soha nem írási cél.

Nem elfogadott dokumentumformátum

Az igazoló dokumentumok PDF, JPG, JPEG, PNG és WEBP formátumban fogadhatók — ugyanazokban, mint az alkalmazásban. Az ellenőrzés a kötelező filename kiterjesztésén történik: az érvényes fájlnév nélküli dokumentumot elutasítjuk, bármi legyen is a tartalma.

A teendő. Küldés előtt konvertáljon (a TIFF vagy HEIC szkennelés PDF-fé vagy JPEG-gé alakítható), és a tartalmat szabványos base64-ként küldje a contenu mezőben, a stabil a_doc_* kódok közül választott type-pal.

6 MB-nál nagyobb dokumentum

A korlát a dekódolt fájlra vonatkozik (6 MB), ugyanúgy, mint az alkalmazásban és a begyűjtő portálon. Mivel a base64 harmadnyi kódolási többletet ad, a kéréstörzs legfeljebb 9 MB-ot fogad.

A teendő. Tömörítse a dokumentumot (egy színes, 300 dpi-vel szkennelt PDF szürkeárnyalatosban szinte mindig a korlát alá kerül), ne darabolja.

A szűrési forrás nem elérhető

A dosszié egyetlen entitását sem lehetett a listákkal összevetni: a forrás (hivataloslista-index vagy szolgáltató) nem válaszolt. Az API megtagadja a következtetést — egy halott forrásra épített „tiszta” jelentés volna a lehető legrosszabb téves negatív. A hibát a dosszién rögzítjük (erreurSource). A részleges kiesés nem váltja ki ezt az 502-t: a 200-as válasz megtartja a válaszoló entitások találatait, és az erreurSourceEntites mezőben nevezi meg a sikerteleneket.

A teendő. Játssza újra ugyanazt a hívást később, ugyanazzal az Idempotency-Key-jel: az idempotencia csak a sikeres válaszokat jegyzi meg — hiba után újrajátszva valódi szűrés fut le.

Beágyazott widgetek nincsenek megnyitva ezen a példányon

A kibocsátó végpont (POST /api/v1/embed/jetons) az Ön irodájához deklarált eredetekre támaszkodik — ez a lista vezérli a beágyazott shell frame-ancestors CSP-jét. Ez az 501 azt mondja, hogy a hívott példány nem hordozza ezt a tárolót: a beágyazási felület ott felépítésből adódóan inert, és ezt mondja ki ahelyett, hogy olyan tokent bocsátana ki, amelyet semmilyen eredet nem tudna soha megjeleníteni. Nem tévesztendő össze a 400-zal, amelyet egy olyan iroda kap, amelynek eredetei még nincsenek deklarálva.

A teendő. Ez az 501 a példányról szól, nem az Ön kéréséről. A vigilae.org-on az Ön irodájának adminisztrátora maga deklarálja az eredeteket, az „Integrációk és biztonság” képernyőn (a widgetek szakasz doboza megmondja, hol); majd játssza le újra ugyanazt a hívást. Semmi sincs javítanivaló a kódjában: a kérés rendben volt, a példány nem volt kész.

A felület nem érhető el ezen a telepítésen

Két alapolvasás — GET /api/v1/dossiers/{id}/origine-fonds és GET /api/v1/dossiers/{id}/exigences — olyan tárolókra épül, amelyeket nem hordoz minden példány. Ha az egyik hiányzik, az API kimondja, ahelyett hogy üres listát adna: a „nincs jelentenivaló” és a „semmit sem olvastunk” ellentétes tények, összekeverésük pedig egy soha meg nem nyitott ügyet kifogástalan ügynek mutatna. Ez a 501 a hívott példányról szól, soha nem a kéréséről és nem is az ügyről.

A teendő. Ne ismételje hurokban: semmi sem változik, amíg a példány nem hordozza azt a tárolót. Kezelje a kódot úgy: „az adat itt nem elérhető”, és főképp ne számolja nullának a műszerfalain — így lesz a hiányzó mérésből rossz szám. A vigilae.org mindkét olvasást kiszolgálja; dedikált telepítésen a tároló bővítése az üzemeltetőjére tartozik.