Každá chyba, vysvětlená na stabilní adrese.

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í.

Tentýž 401 nese "motif": "fin_option_api", když byl klíč zastaven, protože API již není součástí předplatného kanceláře. Datum tohoto zastavení bylo uvedeno v e-mailu správcům kanceláře, nebo, pokud žádní nejsou, na její fakturační adresu, a poté oznamováno v hlavičce Sunset každé odpovědi na přijaté volání (harmonogram v #cle-expiree). Bez motivu může pocházet i z pozastaveného předplatného: pozastavení klíče okamžitě přeruší.

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. Při "motif": "fin_option_api" není chyba v hlavičce ani v klíči: správce kanceláře nám napíše na contact@vigilae.org, aby se API vrátilo do předplatného, a tentýž klíč je znovu přijímán, jakmile se tak stane, až do konce jeho vlastní platnosti.

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ý.

API klíč může přestat být přijímán i před tímto datem, když API již není součástí předplatného kanceláře. Zastavení pak nastane nejméně 30 dní po prvním e-mailu, k datu, které uvede druhý e-mail, odeslaný nejméně 7 dní předem; oba jsou určeny správcům kanceláře, nebo, pokud žádní nejsou, na její fakturační adresu. Jakmile je stanoveno, toto datum je vidět v konzoli kanceláře (pole coupure_le v GET /connect/cles) a každá odpověď na přijaté volání je oznamuje v hlavičce Sunset, dokud nenastane. Po tomto datu volání obdrží 401 popsaný v #authentification, s "motif": "fin_option_api"; pokud se API vrátí do předplatného, klíč je znovu přijímán, až do konce jeho vlastní platnosti.

Náprava. Vytvořte nový klíč, přepněte na něj svá volání, starý odvolejte. U API klíče musí být API stále součástí předplatného kanceláře: bez něj konzole vytvoření klíče odmítne. Naplánujte tuto výměnu ve svém provozu, místo abyste ji objevovali.

Nedostatečný scope

Klíče nesou scopy zaškrtnuté při jejich vytvoření: obecné lecture (čtení, výchozí) a ecriture (zápis), nebo jemné podle zdroje (clients:lecture, pieces:ecriture, origine-fonds:lecture, journal:lecture…).

Dědičnost se řídí příponou, a to jen jedním směrem: lecture pokrývá každé *:lecture, ecriture každé *:ecriture — obráceně to nikdy neplatí; jemný scope otevírá jen sám sebe.

Šest scopů z této dvojice vybočuje a nedědí se ze žádného obecného klíče: alertes:qualifier, embed:emettre, adversemedia:consulter, conformite:consulter, dispositif:consulter, integrite:consulter. Kvalifikace události, vydání tokenu pro vložený widget, čtení nepříznivého tisku ke spisu nebo hodnocení vedení spisu nikdy nevyplývá z obecného práva ke čtení: každý se zaškrtává samostatně.

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, a široký klíč nikdy nenahradí scope, který nebyl výslovně delegován.

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.

Tento účet již existuje

POST /scim/v2/Users na userName, který je pro tuto kancelář již zřízen, odpoví 409 s scimType: uniqueness. Jedinečnost drží databázové omezení, nikoli mezipaměť: dvě souběžná založení nemohou vytvořit dva účty.

Náprava. Berte 409 jako idempotentní úspěch, ne jako chybu: načtěte účet přes ?filter=userName eq "…" a pokračujte s vráceným identifikátorem. Konektor, který na 409 opakuje ve smyčce, nikdy nevytvoří nic navíc.

Tento účet je mimo dosah adresáře

Adresář nemůže účet nesoucí správcovská oprávnění kanceláře ani degradovat, ani deaktivovat: požadavek je odmítnut s scimType: mutability a zapsán do deníku. Bez této hranice by konektor, který převezme adresu osoby odpovědné za compliance, uzavřel kancelář právě tomu, kdo za ni odpovídá.

Náprava. Vyjměte tuto osobu ze synchronizovaného rozsahu, nebo změňte její roli přímo ve Vigilae. Odmítnutí se týká pouze tohoto účtu: zbytek dávky se použije běžně.

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.

Pole, jehož hodnota je příliš dlouhá: Státní příslušnost

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í.

Jiný pokus s tímto klíčem ještě běží

Dva požadavky s týmž Idempotency-Key dorazily zároveň: první se vykoná, druhý je odmítnut před jakýmkoli účinkem. Právě toto odmítnutí zabrání duplicitě. Běžný případ: proxy vrátí 502 nebo 504, zatímco server ještě pracuje, a váš klient požadavek zopakuje. Hlavička Retry-After říká, po kolika sekundách jej zopakovat.

Náprava. Zopakujte tentýž požadavek beze změny, se stejným klíčem, po oznámené prodlevě: dostanete odpověď prvního pokusu. Nikdy nevytvářejte nový klíč, abyste „odblokovali“ — vytvořili byste právě tu duplicitu, které klíč předchází.

Testovací prostředí: kvóta je vyčerpána

Testovací prostředí má pevné limity: 200 karet klientů, 50 spisů a 40 dokladů na spis. Založení nebo vložení, které by kterýkoli z nich překročilo, je odmítnuto před jakýmkoli zápisem a odmítnutí uvádí, o který jde: pole ressource, quota a courant nesou zdroj, strop a aktuální počet v okamžiku odmítnutí. Ze dvou souběžných založení o poslední místo projde jen jedno. Úprava existující karty klienta či existujícího spisu z kvóty nic neubírá.

Náprava. O těchto kvótách se nevyjednává a zopakovaný požadavek dostane stejné odmítnutí. Resetujte testovací prostředí ve svém účtu — začne znovu od ukázkových dat — nebo si sjednejte předplatné: tyto kvóty platí jen pro testovací prostředí.

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.

Uzavřený spis: obchodní vztah byl ukončen

Vztah byl v aplikaci ukončen: spis už nepřijímá zápisy přes API — ani úpravu, ani doklad, ani prověření, ani skutečné majitele. Čtení zůstává otevřené: uzavřený spis lze po celou dobu uchování zobrazit a exportovat.

Náprava. Znovu otevřít vztah je lidský a zaznamenaný úkon v aplikaci; API to za vás neudělá. Je-li operace nová, otevřete nový spis, místo abyste oživovali starý.

Skartovaný spis: údaje byly vymazány

Doba uchování uplynula a údaje spisu byly vymazány. Zůstává jen auditní stopa, která dosvědčuje, že spis existoval a že byl k uvedenému dni skartován; už nepřijímá žádný zápis.

Náprava. Není co opravovat ani opakovat: výmaz je definitivní a zamýšlený. Identifikátor skartovaného spisu uchovaný ve vašich systémech je historie, nikdy cíl zápisu.

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í.

Vložené widgety nejsou na této instanci otevřeny

Vydání tokenu POST /api/v1/embed/jetons se opírá o originy deklarované pro vaši kancelář — právě tento seznam řídí CSP frame-ancestors vloženého shellu. Tento 501 říká, že volaná instance toto úložiště nenese: plocha pro widgety je tam z konstrukce neaktivní, a raději to řekne, než aby vydala token, který by žádný origin nikdy nemohl zobrazit. Nezaměňovat se 400, který dostává kancelář, jejíž originy ještě nejsou deklarovány.

Náprava. Tento 501 se týká instance, ne vašeho požadavku. Na vigilae.org administrátor vaší kanceláře deklaruje originy sám, na obrazovce „Integrace a zabezpečení“ (rámeček v sekci o widgetech říká kde); poté zopakujte totéž volání. Ve vašem kódu není co měnit: požadavek byl v pořádku, instance nebyla připravena.

Plocha nedostupná v tomto nasazení

Dvě základní čtení — GET /api/v1/dossiers/{id}/origine-fonds a GET /api/v1/dossiers/{id}/exigences — se opírají o úložiště, která nenese každá instance. Když jedno chybí, API to řekne, místo aby vrátilo prázdný seznam: „není co hlásit“ a „nic nebylo přečteno“ jsou opačné skutečnosti a jejich záměna by ze spisu, do kterého nikdo nenahlédl, udělala spis bez výhrad. Tento 501 mluví o volané instanci, nikdy o vašem požadavku ani o spisu.

Náprava. Neopakujte volání ve smyčce: dokud instance to úložiště nenese, nic se nezmění. Berte tento kód jako „údaj zde není dostupný“ a hlavně ho nepočítejte jako nulu ve svých přehledech — přesně tak se z chybějícího měření stane špatné číslo. Na vigilae.org jsou obě čtení obsluhována; u vyhrazeného nasazení je povýšení úložiště věcí vašeho provozovatele.