Minden hiba, stabil címen elmagyarázva.
Ez az oldal üzemeltetési referencia, nem reklám. A Connect API minden hibaosztályának állandó horgonya van itt; az API hibaválaszai ezekre a címekre fognak mutatni. A valószínű okot és a teendőt kapja — ebben a sorrendben. Vissza a fejlesztői dokumentációhoz.
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.
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.
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.
A teendő. Hozzon létre új kulcsot, állítsa át a hívásait, vonja vissza a régit. Tervezze be ezt a cserét az üzemeltetésébe, ahelyett hogy meglepetésként érné: a dátum egy évvel előre ismert.
Elégtelen hatókör
A kulcsok lecture (olvasás, az alapértelmezés) és/vagy ecriture (írás) hatókört hordoznak. Egy esemény minősítéséhez ecriture kell; a csak olvasó kulcs 403-at kap, bármi legyen is az erőforrás.
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.
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.
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.
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.
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.
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.
Ez az oldal az API-val együtt fog fejlődni; a meglévő horgonyok címe azonban soha nem változik — nyugodtan eltárolhatja őket az üzemeltetési naplóiban.