Každá chyba, vysvětlená na stabilní adrese.
Tato stránka je provozní reference, ne prodejní řeč. Každá třída chyb API Connect tu má trvalou kotvu; chybové odpovědi API budou na tyto adresy odkazovat. Dostanete pravděpodobnou příčinu a nápravu — v tomto pořadí. Zpět na dokumentaci pro vývojáře.
Klíč chybí, má chybný formát nebo je neznámý
API autentizuje výhradně hlavičkou Authorization: Bearer vgk_… — nikdy session cookie. Odvolaný klíč se stává neznámým v okamžiku odvolání.
Náprava. Ověřte, že hlavička skutečně odchází (proxy ji někdy odstraní), že klíč začíná vgk_ a že nebyl odvolán z konzole kanceláře. Protože se tajemství zobrazuje jen při vytvoření, ztracený klíč se nahrazuje, neobnovuje.
Prošlý klíč
Každý klíč vyprší rok po vytvoření — datum expire_le je v konzoli kanceláře viditelné od prvního dne. Expirační 401 je explicitní: říká, že klíč existoval a už není platný.
Náprava. Vytvořte nový klíč, přepněte na něj svá volání, starý odvolejte. Naplánujte tuto výměnu ve svém provozu, místo abyste ji objevovali: datum je známé rok dopředu.
Nedostatečný scope
Klíče nesou lecture (čtení, výchozí) a/nebo ecriture (zápis). Kvalifikace události vyžaduje ecriture; klíč jen pro čtení dostane 403, ať jde o kterýkoli zdroj.
Náprava. Vytvořte klíč s potřebným scopem — a jen s ním. Nejmenší oprávnění jsou záměr: integrace, která jen čte, nemá důvod držet klíč pro zápis.
Nenalezeno — nebo patří jiné kanceláři
404 znamená, že zdroj neexistuje, nebo patří jiné kanceláři. API tyto dva případy nikdy nerozlišuje: rozlišení by prozradilo, co existuje jinde. Oddělení je vynuceno na úrovni databáze, nejen v aplikačním kódu.
Náprava. Ověřte seq proti deníku kanceláře, jíž klíč patří (GET /api/v1/evenements). Integrujete-li více kanceláří, každá má vlastní klíče: seq mezi kancelářemi necestuje.
Překročený limit požadavků
60 požadavků za minutu na klíč, ve výchozím nastavení (lze upravit pro jednotlivý klíč). Odpověď nese Retry-After a hlavičky X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.
Náprava. Respektujte Retry-After — žádné okamžité opakování. Narazit na limit při pollingu je téměř vždy známkou úplného opětovného načítání: kurzor depuisSeq nikdy znovu nečte, co už bylo přečteno.
Podpis se na vaší straně neověří
Váš příjemce musí přepočítat v1 = HMAC-SHA256(secret, t + "." + body) ze surového přijatého těla a odmítnout každé t starší než 5 minut. Klasická selhání: tělo znovu serializované před ověřením (přeformátovaný JSON už nemá stejné bajty), hodiny rozjeté za toleranci a ignorovaná rotace — po 24 hodin nese hlavička jedno v1 za každé dosud platné tajemství a přijmout musíte, pokud odpovídá kterékoli z nich.
Náprava. Ověřujte proti surovým bajtům, synchronizujte hodiny (NTP), otestujte své ověření během rotace. Ukázky pro Node a Python v dokumentaci dělají přesně tohle — raději je zkopírujte, než abyste je psali znovu.
Událost dorazí dvakrát
Doručení je at-least-once, v dávkách po nejvýše 100, v pořadí deníku; kurzor se posouvá jen po vašem 2xx, dávku po dávce. Selhání po přijetí, ale před posunem kurzoru vyvolá opětovné doručení — to je kontrakt, ne vada.
Náprava. seq je váš idempotenční klíč: každou sekvenci zpracujte právě jednou a 2xx odpovídejte až po uložení. Předčasné 2xx následované pádem je jediný způsob, jak o událost přijít.
Deník vypadá neúplně nebo se opakuje
depuisSeq je striktně exkluzivní: vracejí se jen události s vyšším seq, seřazené vzestupně, nejvýše 500 na stránku. Odpověď vrací prochainSeq, který předáte beze změny. Stránka kratší než limite znamená konec deníku.
Náprava. Ukládejte prochainSeq mezi běhy a nikdy jej nepočítejte sami. Duplicity znamenají, že jste vyšli z příliš starého kurzoru; mezery znamenají, že jste přeskočili neúspěšnou stránku, aniž byste ji zopakovali.
Parametr mimo schéma
Neznámý stav, vyřízení mimo seznam (planifie, traite, ecarte), neceločíselná limite: odpověď pojmenuje problémové pole a nic víc — chybové zprávy nikdy nenesou obsah spisu.
Náprava. Zdrojem je specifikace OpenAPI: výčty a meze, které deklaruje, jsou ty, jež server vynucuje — vždyť ji sám servíruje.
Nedostatečný scope (API zdrojů)
Endpointy zdrojů (/clients, /dossiers, doklady, prověřování, upozornění) vyžadují jemný scope: clients:*, dossiers:*, pieces:*, criblage:* nebo vyhrazený scope alertes:qualifier. Starší klíč lecture uděluje všechny scopy *:lecture a ecriture všechny *:ecriture — ale alertes:qualifier se nikdy nedědí: kvalifikace upozornění je úkon odpovědné osoby, delegovaný zaškrtnutím tohoto scopu při vytvoření klíče.
Náprava. Vytvořte klíč přesně s těmi scopy, které vaše integrace potřebuje — a jen s nimi. Pole detail v odpovědi pojmenuje chybějící scope.
Zdroj nenalezen — nebo patří jiné kanceláři
Stejné pravidlo jako #cloisonnement, uplatněné na zdroje: klient, spis, doklad nebo upozornění, které neexistuje, nebo patří jiné kanceláři, dostane týž 404. API tyto dva případy nikdy nerozliší.
Náprava. Ověřte identifikátor proti výpisům kanceláře, jíž klíč patří. Identifikátor nikdy necestuje z jedné kanceláře do druhé.
Chybí hlavička Idempotency-Key
Každý POST, který vytváří nebo spouští (klient, spis, doklad, prověření, skuteční majitelé), vyžaduje hlavičku Idempotency-Key: stabilní řetězec o nejvýše 200 znacích, jeden na operaci. Zopakování téhož klíče se stejným tělem vrátí stejnou odpověď, bez účinku — vaše ochrana proti duplicitám při síťovém incidentu.
Náprava. Klíč vygenerujte před prvním pokusem (jedno UUID na obchodní operaci) a beze změny jej použijte při každém opakování téže operace.
Idempotenční klíč znovu použitý s jiným tělem
Tento Idempotency-Key už byl během posledních 24 hodin použit pro jiné tělo. Klíč přehrává odpověď, nikdy ji nepřepisuje: jeho opětovné použití pro novou operaci je téměř vždy známkou klíče odvozeného z čítače nebo zkráceného data.
Náprava. Nový klíč pro každou novou operaci. Nikdy klíč neodvozujte z údajů, které se mezi operacemi opakují.
Zapečetěný spis: registr je zmrazen
Zapečetění zmrazí integritní řetězec spisu — v tom spočívá jeho důkazní hodnota. Zapečetěný spis už nelze upravovat, nepřijímá doklady a tímto kanálem se už znovu neprověřuje. Možná zůstává jen kvalifikace upozornění: zapisuje se mimo řetězec, zapečetěná hlava se nikdy nepohne.
Náprava. Není co „opravovat“: jde o záměrnou neměnnost. Musí-li se údaje změnit, je to nová operace obezřetnosti v aplikaci, ne mutace zapečetěného spisu.
Nepřijímaný formát dokladu
Doklady přijímají PDF, JPG, JPEG, PNG a WEBP — stejné formáty jako aplikace. Kontrola probíhá na příponě povinného filename: doklad bez platného názvu souboru je odmítnut, ať je jeho obsah jakýkoli.
Náprava. Před odesláním převeďte (sken TIFF nebo HEIC se převede do PDF nebo JPEG) a obsah pošlete jako standardní base64 v poli contenu, s type z řady stabilních kódů a_doc_*.
Doklad nad 6 MB
Limit platí pro dekódovaný soubor (6 MB), stejně jako v aplikaci a na portálu pro sběr dokladů. Protože base64 přidává třetinu kódovací režie, tělo požadavku přijme až 9 MB.
Náprava. Doklad raději zkomprimujte (barevné PDF skenované ve 300 dpi se v odstínech šedi téměř vždy dostane pod limit), než abyste jej dělili.
Zdroj prověřování nedostupný
Žádnou z entit spisu nebylo možné ověřit proti seznamům: zdroj (index úředních seznamů nebo poskytovatel) neodpověděl. API odmítá učinit závěr — „čistý“ výsledek nad mrtvým zdrojem by byl nejhorší možný falešně negativní nález. Selhání se zaznamená do spisu (erreurSource). Částečný výpadek tento 502 nevyvolá: odpověď 200 ponechá shody entit, které odpověděly, a ty neúspěšné pojmenuje v erreurSourceEntites.
Náprava. Zopakujte později totéž volání, se stejným Idempotency-Key: idempotence si pamatuje jen úspěšné odpovědi — opakování po chybě spustí skutečné prověření.
Tato stránka se bude vyvíjet spolu s API; existující kotvy však nikdy nemění adresu — můžete si je ukládat do svých provozních logů.