Každá chyba, vysvetlená na stálej adrese.

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.

Ten istý 401 nesie "motif": "fin_option_api", keď bol kľúč zastavený, pretože API už nie je súčasťou predplatného kancelárie. Dátum tohto zastavenia bol uvedený v e-maile správcom kancelárie, alebo, ak žiadni nie sú, na jej fakturačnú adresu, a potom oznamovaný v hlavičke Sunset každej odpovede na prijaté volanie (harmonogram v #cle-expiree). Bez motívu môže pochádzať aj z pozastaveného predplatného: pozastavenie kľúče okamžite preruší.

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. Pri "motif": "fin_option_api" nie je chyba v hlavičke ani v kľúči: správca kancelárie nám napíše na contact@vigilae.org, aby sa API vrátilo do predplatného, a ten istý kľúč je opäť prijímaný, len čo sa tak stane, až do konca jeho vlastnej platnosti.

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

API kľúč môže prestať byť prijímaný aj pred týmto dátumom, keď API už nie je súčasťou predplatného kancelárie. Zastavenie potom nastane najmenej 30 dní po prvom e-maile, k dátumu, ktorý uvedie druhý e-mail, odoslaný najmenej 7 dní vopred; oba sú určené správcom kancelárie, alebo, ak žiadni nie sú, na jej fakturačnú adresu. Len čo je stanovený, tento dátum je viditeľný v konzole kancelárie (pole coupure_le v GET /connect/cles) a každá odpoveď na prijaté volanie ho oznamuje v hlavičke Sunset, kým nenastane. Po tomto dátume volanie dostane 401 opísaný v #authentification, s "motif": "fin_option_api"; ak sa API vráti do predplatného, kľúč je opäť prijímaný, až do konca jeho vlastnej platnosti.

Náprava. Vytvorte nový kľúč, prepnite naň svoje volania, starý odvolajte. Pri API kľúči musí byť API stále súčasťou predplatného kancelárie: bez neho konzola vytvorenie kľúča odmietne. Túto výmenu si naplánujte v prevádzke, namiesto toho, aby ste ju objavovali.

Nedostatočný rozsah oprávnení

Kľúče nesú rozsahy zaškrtnuté pri ich vytvorení: všeobecné lecture (čítanie, predvolené) a ecriture (zápis) alebo jemné podľa zdroja (clients:lecture, pieces:ecriture, origine-fonds:lecture, journal:lecture…).

Dedenie sa riadi príponou, a to len jedným smerom: lecture pokrýva každé *:lecture, ecriture každé *:ecriture — opačne nikdy; jemný rozsah otvára len sám seba.

Šesť rozsahov z tejto dvojice vybočuje a nededí sa zo žiadneho všeobecného kľúča: alertes:qualifier, embed:emettre, adversemedia:consulter, conformite:consulter, dispositif:consulter, integrite:consulter. Kvalifikácia udalosti, vydanie tokenu pre vložený widget, čítanie nepriaznivej tlače k spisu alebo hodnotenia vedenia spisu nikdy nevyplýva zo všeobecného práva na čítanie: každý sa zaškrtáva zvlášť.

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ľúč, a široký kľúč nikdy nenahradí rozsah, ktorý nebol výslovne delegovaný.

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.

Tento účet už existuje

POST /scim/v2/Users na userName, ktorý je pre túto kanceláriu už zriadený, odpovie 409 s scimType: uniqueness. Jedinečnosť drží databázové obmedzenie, nie vyrovnávacia pamäť: dve súbežné založenia nemôžu vytvoriť dva účty.

Náprava. Berte 409 ako idempotentný úspech, nie ako chybu: načítajte účet cez ?filter=userName eq "…" a pokračujte s vráteným identifikátorom. Konektor, ktorý pri 409 opakuje v slučke, nikdy nevytvorí nič navyše.

Tento účet je mimo dosahu adresára

Adresár nemôže účet nesúci správcovské oprávnenia kancelárie ani degradovať, ani deaktivovať: požiadavka sa odmietne s scimType: mutability a zapíše do denníka. Bez tejto hranice by konektor, ktorý prevezme adresu osoby zodpovednej za súlad, uzavrel kanceláriu práve tomu, kto za ňu zodpovedá.

Náprava. Vyberte túto osobu zo synchronizovaného rozsahu alebo zmeňte jej rolu priamo vo Vigilae. Odmietnutie sa týka len tohto účtu: zvyšok dávky sa použije bežne.

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.

Pole, ktorého hodnota je príliš dlhá: Štátna príslušnosť

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

Iný pokus s týmto kľúčom ešte beží

Dve požiadavky s tým istým Idempotency-Key prišli súčasne: prvá sa vykoná, druhá je odmietnutá pred akýmkoľvek účinkom. Práve toto odmietnutie zabráni duplicite. Bežný prípad: proxy vráti 502 alebo 504, kým server ešte pracuje, a váš klient požiadavku zopakuje. Hlavička Retry-After hovorí, po koľkých sekundách ju zopakovať.

Náprava. Zopakujte tú istú požiadavku bez zmeny, s rovnakým kľúčom, po oznámenom čakaní: dostanete odpoveď prvého pokusu. Nikdy nevytvárajte nový kľúč, aby ste „odblokovali“ — vytvorili by ste práve tú duplicitu, ktorej kľúč predchádza.

Testovacie prostredie: kvóta vyčerpaná

Testovacie prostredie má pevné limity: 200 kariet klientov, 50 spisov a 40 dokladov na spis. Založenie alebo nahratie, ktoré by niektorý z nich prekročilo, je odmietnuté pred akýmkoľvek zápisom a odmietnutie uvedie, ktorý: polia ressource, quota a courant nesú zdroj, strop a počet v okamihu odmietnutia. Z dvoch súbežných založení o posledné miesto prejde len jedno. Úprava existujúcej karty alebo spisu nič nespotrebuje.

Náprava. O týchto kvótach sa nerokuje a zopakovanie požiadavky vráti rovnaké odmietnutie. Obnovte testovacie prostredie do pôvodného stavu vo svojom priestore — začne znova s ukážkovými údajmi — alebo si objednajte predplatné: tieto kvóty platia len pre testovacie prostredia.

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.

Uzavretý spis: obchodný vzťah sa skončil

Vzťah bol v aplikácii ukončený: spis už neprijíma zápisy cez API — ani úpravu, ani doklad, ani preverenie, ani konečných užívateľov výhod. Čítanie zostáva otvorené: uzavretý spis možno po celý čas uchovávania zobraziť a exportovať.

Náprava. Obnoviť vzťah je ľudský a zaznamenaný úkon v aplikácii; API to za vás neurobí. Ak je operácia nová, otvorte nový spis namiesto oživovania starého.

Vymazaný spis: údaje boli odstránené

Lehota uchovávania uplynula a údaje spisu boli vymazané. Zostáva len auditná stopa, ktorá dosvedčuje, že spis existoval a že bol k uvedenému dňu vymazaný; už neprijíma žiadny zápis.

Náprava. Niet čo opravovať ani opakovať: výmaz je definitívny a zamýšľaný. Identifikátor vymazaného spisu uchovaný vo vašich systémoch je história, nikdy cieľ zápisu.

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.

Vložené widgety nie sú na tejto inštancii aktivované

Vydávanie tokenov POST /api/v1/embed/jetons sa spolieha na originy deklarované pre vašu kanceláriu — práve tento zoznam riadi CSP frame-ancestors vloženého shellu. Táto 501 hovorí, že volaná inštancia toto úložisko nemá: plocha widgetov je tam neaktívna už svojou konštrukciou a radšej to povie, než aby vydala token, ktorý by žiadny origin nikdy nemohol zobraziť. Nezamieňať so 400, ktorú dostane kancelária, ktorej originy ešte nie sú deklarované.

Náprava. Táto 501 hovorí o inštancii, nie o vašej požiadavke. Na vigilae.org administrátor vašej kancelárie deklaruje originy sám, na obrazovke „Integrácie a bezpečnosť“ (kde presne, hovorí rámček v sekcii widgetov); potom zopakujte to isté volanie. Vo vašom kóde nie je čo meniť: požiadavka bola v poriadku, inštancia nebola pripravená.

Plocha nedostupná v tomto nasadení

Dve základné čítania — GET /api/v1/dossiers/{id}/origine-fonds a GET /api/v1/dossiers/{id}/exigences — sa opierajú o úložiská, ktoré nenesie každá inštancia. Keď jedno chýba, API to povie namiesto toho, aby vrátilo prázdny zoznam: „niet čo hlásiť“ a „nič sa neprečítalo“ sú opačné skutočnosti a ich zámena by zo spisu, do ktorého nikto nenazrel, urobila spis bez výhrad. Tento 501 hovorí o volanej inštancii, nikdy o vašej požiadavke ani o spise.

Náprava. Neopakujte volanie v slučke: kým inštancia to úložisko nenesie, nič sa nezmení. Berte tento kód ako „údaj tu nie je dostupný“ a najmä ho nepočítajte ako nulu vo svojich prehľadoch — presne tak sa z chýbajúceho merania stane zlé číslo. Na vigilae.org sú obe čítania obsluhované; pri vyhradenom nasadení je povýšenie úložiska vecou vášho prevádzkovateľa.