Každá chyba, vysvetlená na stálej adrese.
Táto stránka je prevádzková referencia, nie predajný text. Každá trieda chýb Connect API tu má trvalú kotvu; chybové odpovede API budú na tieto adresy odkazovať. Dostanete pravdepodobnú príčinu a nápravu — v tomto poradí. Späť na dokumentáciu pre vývojárov.
Kľúč chýba, je poškodený alebo neznámy
API autentifikuje výlučne cez hlavičku Authorization: Bearer vgk_… — nikdy cez session cookie. Odvolaný kľúč sa stáva neznámym v okamihu odvolania.
Náprava. Overte, že hlavička skutočne odchádza (proxy ju niekedy odstraňujú), že kľúč sa začína vgk_ a že nebol odvolaný z konzoly kancelárie. Keďže tajomstvo sa zobrazuje len pri vytvorení, stratený kľúč sa nahrádza, nie obnovuje.
Expirovaný kľúč
Každý kľúč expiruje rok po vytvorení — dátum expire_le je v konzole kancelárie viditeľný od prvého dňa. Expiračná 401 je explicitná: hovorí, že kľúč existoval a už nie je platný.
Náprava. Vytvorte nový kľúč, prepnite naň svoje volania, starý odvolajte. Túto výmenu si naplánujte v prevádzke, namiesto toho, aby ste ju objavovali: dátum je známy rok dopredu.
Nedostatočný rozsah oprávnení
Kľúče nesú lecture (čítanie, predvolené) a/alebo ecriture (zápis). Kvalifikácia udalosti vyžaduje ecriture; kľúč len na čítanie dostane 403 bez ohľadu na zdroj.
Náprava. Vytvorte kľúč s potrebným rozsahom — a len s ním. Najmenšie oprávnenie je zámer: integrácia, ktorá len číta, nemá dôvod držať zapisovací kľúč.
Nenájdené — alebo patrí inej kancelárii
404 znamená, že zdroj neexistuje, alebo patrí inej kancelárii. API tieto dva prípady nikdy nerozlišuje: rozlíšenie by prezradilo, čo existuje inde. Oddelenie sa vynucuje na úrovni databázy, nielen v aplikačnom kóde.
Náprava. Overte seq voči denníku kancelárie, ktorej kľúč patrí (GET /api/v1/evenements). Ak integrujete viacero kancelárií, každá má vlastné kľúče: seq necestuje medzi kanceláriami.
Prekročený limit požiadaviek
60 požiadaviek za minútu na kľúč, predvolene (dá sa upraviť pre jednotlivý kľúč). Odpoveď nesie Retry-After a hlavičky X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.
Náprava. Rešpektujte Retry-After — žiadne okamžité opakovanie. Náraz na limit pri dopytovaní je takmer vždy znakom úplného preskenovania: kurzor depuisSeq nikdy znovu nečíta to, čo už bolo prečítané.
Podpis sa na vašej strane neoveruje
Váš prijímač musí prepočítať v1 = HMAC-SHA256(secret, t + "." + body) zo surového prijatého tela a odmietnuť každé t staršie než 5 min. Klasické zlyhania: telo pred overením nanovo serializované (preformátovaný JSON už nemá tie isté bajty), hodiny unesené za hranicu tolerancie a ignorovaná rotácia — počas 24 h nesie hlavička jedno v1 za každé ešte platné tajomstvo a prijať musíte, ak sa zhoduje ktorékoľvek.
Náprava. Overujte voči surovým bajtom, synchronizujte si hodiny (NTP), otestujte svoje overenie počas rotácie. Úryvky pre Node a Python v dokumentácii robia presne toto — skopírujte ich, namiesto toho, aby ste ich písali nanovo.
Udalosť príde dvakrát
Doručovanie je at-least-once, v dávkach najviac po 100, v poradí denníka; kurzor sa posúva len po vašej 2xx, dávku po dávke. Zlyhanie po prijatí, ale pred posunom kurzora, spôsobí opätovné doručenie — to je kontrakt, nie chyba.
Náprava. seq je váš idempotenčný kľúč: každú sekvenciu spracujte práve raz a 2xx odpovedzte až po uložení. Predčasná 2xx nasledovaná pádom je jediný spôsob, ako udalosť stratiť.
Denník vyzerá neúplný alebo sa opakuje
depuisSeq je striktne exkluzívny: vracajú sa len udalosti s vyšším seq, zoradené vzostupne, najviac 500 na stránku. Odpoveď vracia prochainSeq, ktorý odovzdáte bezo zmeny. Stránka kratšia než limite znamená koniec denníka.
Náprava. Ukladajte si prochainSeq medzi behmi a nikdy si ho neprepočítavajte sami. Duplicity znamenajú, že ste sa reštartovali z pristarého kurzora; medzery znamenajú, že ste preskočili zlyhanú stránku bez jej zopakovania.
Parameter mimo schémy
Neznámy stav, dispozícia mimo zoznamu (planifie, traite, ecarte), neceločíselný limite: odpoveď pomenuje chybné pole a nič iné — chybové správy nikdy nenesú obsah spisov.
Náprava. Zdrojom je špecifikácia OpenAPI: enumerácie a hranice, ktoré deklaruje, sú tie, ktoré server vynucuje, keďže ju sám servíruje.
Nedostatočný rozsah oprávnení (zdrojové API)
Zdrojové endpointy (/clients, /dossiers, doklady, preverovanie, poplachy) vyžadujú jemne členený rozsah: clients:*, dossiers:*, pieces:*, criblage:* alebo vyhradený rozsah alertes:qualifier. Starší kľúč lecture udeľuje všetky rozsahy *:lecture a ecriture všetky *:ecriture — no alertes:qualifier sa nikdy nededí: kvalifikácia poplachu je úkonom zodpovednej osoby, delegovaným zaškrtnutím tohto rozsahu pri vytváraní kľúča.
Náprava. Vytvorte kľúč presne s tými rozsahmi, ktoré vaša integrácia potrebuje — a len s nimi. Pole detail v odpovedi pomenuje chýbajúci rozsah.
Zdroj nenájdený — alebo patrí inej kancelárii
Rovnaké pravidlo ako #cloisonnement, uplatnené na zdroje: klient, spis, doklad alebo poplach, ktorý neexistuje, alebo patrí inej kancelárii, dostane rovnakú 404. API tieto dva prípady nikdy nerozlišuje.
Náprava. Overte identifikátor voči zoznamom kancelárie, ktorej kľúč patrí. Identifikátor nikdy necestuje z jednej kancelárie do druhej.
Chýba hlavička Idempotency-Key
Každý vytvárajúci alebo spúšťajúci POST (klient, spis, doklad, preverenie, koneční užívatelia výhod) vyžaduje hlavičku Idempotency-Key: stabilný reťazec s najviac 200 znakmi, jeden na operáciu. Zopakovanie rovnakého kľúča s rovnakým telom vráti rovnakú odpoveď, bez účinku — vaša ochrana pred duplicitami pri sieťovom incidente.
Náprava. Kľúč vygenerujte pred prvým pokusom (jedno UUID na obchodnú operáciu) a bezo zmeny ho použite pri každom opakovaní tej istej operácie.
Idempotenčný kľúč znovu použitý s iným telom
Tento Idempotency-Key už bol za posledných 24 hodín použitý s iným telom. Kľúč prehráva odpoveď, nikdy ju neprepisuje: jeho opätovné použitie na novú operáciu je takmer vždy znakom kľúča odvodeného z počítadla alebo zo skráteného dátumu.
Náprava. Nový kľúč pre každú novú operáciu. Kľúč nikdy neodvodzujte z údajov, ktoré sa medzi operáciami opakujú.
Zapečatený spis: register je zmrazený
Zapečatenie zmrazí integritnú reťaz spisu — v tom je jeho dôkazná hodnota. Zapečatený spis sa už nedá upravovať, neprijíma doklady a týmto kanálom sa už opätovne nepreveruje. Možná zostáva len kvalifikácia poplachov: zapisuje sa mimo reťaze, zapečatená hlava sa nikdy nepohne.
Náprava. Niet čo „opravovať“: ide o zámernú nemennosť. Ak sa údaje musia zmeniť, je to nová operácia náležitej starostlivosti v aplikácii, nie mutácia zapečateného spisu.
Neakceptovaný formát dokladu
Doklady akceptujú PDF, JPG, JPEG, PNG a WEBP — rovnaké formáty ako aplikácia. Kontrola prebieha na prípone povinného filename: doklad bez platného názvu súboru je odmietnutý bez ohľadu na obsah.
Náprava. Pred odoslaním konvertujte (sken TIFF alebo HEIC sa konvertuje na PDF alebo JPEG) a obsah pošlite ako štandardný base64 v contenu, s type spomedzi stabilných kódov a_doc_*.
Doklad nad 6 MB
Limit sa vzťahuje na dekódovaný súbor (6 MB), rovnako ako v aplikácii a v zbernom portáli. Keďže base64 pridáva tretinu kódovacej réžie, telo požiadavky prijme až 9 MB.
Náprava. Doklad komprimujte (farebný PDF skenovaný na 300 dpi sa v odtieňoch sivej takmer vždy dostane pod limit), namiesto toho, aby ste ho delili.
Zdroj preverovania nedostupný
Ani jeden subjekt spisu sa nepodarilo overiť voči zoznamom: zdroj (index oficiálnych zoznamov alebo poskytovateľ) neodpovedal. API odmieta uzavrieť záver — „čistý“ výsledok nad mŕtvym zdrojom by bol najhorší možný falošný negatív. Zlyhanie sa zaznamená na spise (erreurSource). Čiastočný výpadok túto 502 nevyvolá: odpoveď 200 si ponechá zhody subjektov, ktoré odpovedali, a zlyhané pomenuje v erreurSourceEntites.
Náprava. Zopakujte neskôr to isté volanie, s rovnakou Idempotency-Key: idempotencia si pamätá len úspešné odpovede — zopakovanie po chybe spustí skutočné preverenie.
Táto stránka sa bude vyvíjať spolu s API; existujúce kotvy však nikdy nemenia adresu — môžete si ich ukladať do prevádzkových logov.