Svaka pogreška, objašnjena na stabilnoj adresi.

Ključ nedostaje, neispravan je ili je nepoznat

API se autentificira isključivo zaglavljem Authorization: Bearer vgk_… — nikada kolačićem sesije. Opozvani ključ postaje nepoznat u trenutku opoziva.

Isti 401 nosi "motif": "fin_option_api" kad je ključ zaustavljen jer API više nije dio pretplate ureda. Datum tog zaustavljanja naveden je u e-poruci administratorima ureda ili, ako ih nema, na adresu za naplatu ureda, a zatim najavljivan u zaglavlju Sunset svakog odgovora na prihvaćeni poziv (raspored u #cle-expiree). Bez motiva može potjecati i od suspendirane pretplate: suspenzija odmah prekida ključeve.

Rješenje. Provjerite da zaglavlje doista izlazi (proxyji ga ponekad uklone), da ključ počinje s vgk_ i da nije opozvan iz konzole ureda. Budući da se tajna prikazuje samo pri stvaranju, izgubljeni ključ se zamjenjuje, ne obnavlja. Uz "motif": "fin_option_api" problem nije ni u zaglavlju ni u ključu: administrator ureda piše nam na contact@vigilae.org da se API vrati u pretplatu, a isti se ključ ponovno prihvaća čim se to dogodi, do isteka vlastitog roka valjanosti.

Istekli ključ

Svaki ključ istječe godinu dana nakon stvaranja — datum expire_le vidljiv je u konzoli ureda od prvog dana. 401 zbog isteka je izričit: kaže da je ključ postojao i da više ne vrijedi.

API ključ se može prestati prihvaćati i prije tog datuma, kad API više nije dio pretplate ureda. Zaustavljanje tada nastupa najmanje 30 dana nakon prve e-poruke, na datum koji navodi druga e-poruka, poslana najmanje 7 dana unaprijed; obje se šalju administratorima ureda ili, ako ih nema, na adresu za naplatu ureda. Čim se odredi, taj je datum vidljiv u konzoli ureda (polje coupure_le u GET /connect/cles), a svaki ga odgovor na prihvaćeni poziv najavljuje u zaglavlju Sunset dok ne nastupi. Nakon tog datuma poziv dobiva 401 opisan u #authentification, s "motif": "fin_option_api"; ako se API vrati u pretplatu, ključ se ponovno prihvaća, do isteka vlastitog roka valjanosti.

Rješenje. Stvorite novi ključ, prebacite svoje pozive, opozovite stari. Za API ključ API mora i dalje biti dio pretplate ureda: bez njega konzola odbija stvoriti ključ. Zamjenu uvrstite u svoje operativne planove umjesto da je otkrivate.

Nedovoljan opseg

Ključevi nose opsege označene pri njihovu stvaranju: opće lecture (čitanje, zadano) i ecriture (pisanje) ili fine po resursu (clients:lecture, pieces:ecriture, origine-fonds:lecture, journal:lecture…).

Nasljeđivanje ide po sufiksu, samo u jednom smjeru: lecture pokriva svaki *:lecture, ecriture svaki *:ecriture — obrnuto nikada; fini opseg otvara samo sebe.

Šest opsega izlazi iz tog para i ne nasljeđuje se ni iz jednog općeg ključa: alertes:qualifier, embed:emettre, adversemedia:consulter, conformite:consulter, dispositif:consulter, integrite:consulter. Kvalificiranje događaja, izdavanje tokena za ugrađeni widget, čitanje nepovoljnog tiska uz predmet ili ocjene vođenja predmeta nikada ne proizlazi iz općeg prava čitanja: svaki se označava zasebno.

Rješenje. Stvorite ključ s potrebnim opsegom — i samo njim. Najmanja ovlast je namjerna: integracija koja samo čita nema razloga držati ključ za pisanje, a širok ključ nikada neće nadoknaditi opseg koji nije izričito delegiran.

Nije pronađeno — ili pripada drugom uredu

404 znači da resurs ne postoji ili pripada drugom uredu. API ta dva slučaja nikada ne razlikuje: razlikovanje bi otkrilo što postoji drugdje. Odvajanje se provodi na razini baze podataka, ne samo u aplikacijskom kodu.

Rješenje. Provjerite seq u dnevniku ureda kojem ključ pripada (GET /api/v1/evenements). Ako integrirate više ureda, svaki ured ima vlastite ključeve: seq ne putuje između ureda.

Ovaj račun već postoji

POST /scim/v2/Users na userName koji je za ovaj ured već otvoren odgovara s 409 i scimType: uniqueness. Jedinstvenost drži ograničenje baze podataka, a ne predmemorija: dva istodobna otvaranja ne mogu proizvesti dva računa.

Rješenje. Tretirajte 409 kao idempotentan uspjeh, a ne kao pogrešku: ponovno pročitajte račun s ?filter=userName eq "…" i nastavite s vraćenim identifikatorom. Konektor koji nakon 409 ponavlja u petlji nikada neće stvoriti ništa više.

Ovaj je račun izvan dosega imenika

Imenik ne može ni sniziti ni onemogućiti račun koji nosi ovlasti upravljanja uredom: zahtjev se odbija s scimType: mutability i bilježi. Bez te granice konektor koji preuzme adresu osobe odgovorne za usklađenost zatvorio bi ured upravo onome tko za njega odgovara.

Rješenje. Uklonite tu osobu iz usklađivanog opsega ili joj promijenite ulogu unutar Vigilae. Odbijanje se odnosi samo na ovaj račun: ostatak serije primjenjuje se uobičajeno.

Prekoračen broj zahtjeva

60 zahtjeva u minuti po ključu, prema zadanim postavkama (podesivo po ključu). Odgovor nosi Retry-After te zaglavlja X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.

Rješenje. Poštujte Retry-After — bez trenutačnog ponavljanja. Udarac u limit tijekom prozivanja gotovo je uvijek znak potpunog ponovnog čitanja: kursor depuisSeq nikada ponovno ne čita već pročitano.

Potpis se ne potvrđuje na vašoj strani

Vaš prijamnik mora ponovno izračunati v1 = HMAC-SHA256(secret, t + "." + body) iz sirovog primljenog tijela i odbaciti svaki t stariji od 5 min. Klasični promašaji: tijelo ponovno serijalizirano prije provjere (preformatirani JSON više nema iste bajtove), sat koji odluta izvan tolerancije i zanemarena rotacija — 24 h zaglavlje nosi po jedan v1 za svaku još valjanu tajnu, a morate prihvatiti ako se bilo koji podudara.

Rješenje. Provjeravajte nad sirovim bajtovima, sinkronizirajte sat (NTP), ispitajte svoju provjeru tijekom rotacije. Node i Python isječci u dokumentaciji rade upravo to — kopirajte ih umjesto da ih pišete iznova.

Događaj stiže dvaput

Isporuka je at-least-once, u serijama od najviše 100, redoslijedom dnevnika; kursor napreduje samo na vaš 2xx, seriju po seriju. Kvar nakon primitka, a prije pomaka kursora, uzrokuje ponovnu isporuku — to je ugovor, ne nedostatak.

Rješenje. seq je vaš idempotencijski ključ: svaku sekvencu obradite točno jednom i 2xx odgovorite tek nakon trajne pohrane. Preuranjeni 2xx praćen padom jedini je način da izgubite događaj.

Dnevnik izgleda nepotpun ili se ponavlja

depuisSeq je strogo ekskluzivan: vraćaju se samo događaji s višim seq, sortirani uzlazno, najviše 500 po stranici. Odgovor vraća prochainSeq, koji proslijedite nepromijenjen. Stranica kraća od limite znači kraj dnevnika.

Rješenje. Trajno pohranjujte prochainSeq između izvođenja i nikada ga ne računajte sami. Duplikati znače da ste krenuli od prestarog kursora; rupe znače da ste preskočili neuspjelu stranicu bez njezina ponavljanja.

Parametar izvan sheme

Nepoznat status, ishod izvan popisa (planifie, traite, ecarte), necjelobrojni limite: odgovor imenuje sporno polje, i ništa više — poruke o pogrešci nikada ne nose sadržaj spisa.

Rješenje. OpenAPI specifikacija je izvor: enumeracije i granice koje deklarira upravo su one koje poslužitelj provodi, budući da je on i poslužuje.

Polje čija je vrijednost predugačka: Državljanstvo

Odgovor imenuje sporno polje, i ništa više — poruke o pogrešci nikada ne nose sadržaj spisa.

Rješenje. OpenAPI specifikacija je izvor: enumeracije i granice koje deklarira upravo su one koje poslužitelj provodi, budući da je on i poslužuje.

Nedovoljan opseg (API resursa)

Krajnje točke resursa (/clients, /dossiers, dokumenti, provjera prema popisima, upozorenja) zahtijevaju fino zrnat opseg: clients:*, dossiers:*, pieces:*, criblage:* ili namjenski opseg alertes:qualifier. Naslijeđeni ključ lecture daje svaki opseg *:lecture, a ecriture svaki *:ecriture — ali alertes:qualifier nikada se ne nasljeđuje: kvalificiranje upozorenja čin je odgovorne osobe, delegiran označavanjem tog opsega pri stvaranju ključa.

Rješenje. Stvorite ključ s točno onim opsezima koje vaša integracija treba — i samo njima. Polje detail u odgovoru imenuje nedostajući opseg.

Resurs nije pronađen — ili pripada drugom uredu

Isto pravilo kao #cloisonnement, primijenjeno na resurse: stranka, spis, dokument ili upozorenje koje ne postoji ili pripada drugom uredu dobiva isti 404. API ta dva slučaja nikada ne razlikuje.

Rješenje. Provjerite identifikator u popisima ureda kojem ključ pripada. Identifikator nikada ne putuje iz jednog ureda u drugi.

Nedostaje zaglavlje Idempotency-Key

Svaki POST koji stvara ili pokreće (stranka, spis, dokument, provjera prema popisima, stvarni vlasnici) zahtijeva zaglavlje Idempotency-Key: stabilan niz od najviše 200 znakova, jedan po operaciji. Ponavljanje istog ključa s istim tijelom vraća isti odgovor, bez učinka — vaša zaštita od duplikata pri mrežnom incidentu.

Rješenje. Generirajte ključ prije prvog pokušaja (jedan UUID po poslovnoj operaciji) i koristite ga nepromijenjenog pri svakom ponavljanju te iste operacije.

Idempotencijski ključ ponovno upotrijebljen s drukčijim tijelom

Ovaj Idempotency-Key već je upotrijebljen za drukčije tijelo u posljednja 24 sata. Ključ ponovno vraća odgovor, nikada ga ne prepisuje: njegova ponovna upotreba za novu operaciju gotovo je uvijek znak ključa izvedenog iz brojača ili skraćenog datuma.

Rješenje. Novi ključ za svaku novu operaciju. Ključ nikada ne izvodite iz podataka koji se ponavljaju kroz operacije.

Drugi pokušaj s ovim ključem još je u tijeku

Dva zahtjeva s istim Idempotency-Key stigla su zajedno: prvi se izvršava, drugi se odbija prije svakog učinka. Upravo to odbijanje sprječava duplikat. Uobičajen slučaj: proxy vrati 502 ili 504 dok poslužitelj još radi, a vaš klijent ponovi zahtjev. Zaglavlje Retry-After govori nakon koliko sekundi ga ponoviti.

Rješenje. Ponovite isti zahtjev, nepromijenjen, s istim ključem, nakon najavljenog čekanja: dobit ćete odgovor prvog pokušaja. Nikada ne izmišljajte novi ključ da biste „odblokirali” — time biste stvorili upravo duplikat koji ključ sprječava.

Testno okruženje: kvota je dosegnuta

Testno okruženje ima fiksna ograničenja: 200 kartica stranaka, 50 spisa i 40 dokumenata po spisu. Stvaranje ili predaja dokumenta koja bi premašila jedno od njih odbija se prije nego što se išta zapiše, a odbijanje navodi o kojem je ograničenju riječ: polja ressource, quota i courant nose resurs, gornju granicu i broj zapisa u trenutku odbijanja. Kad se dva istodobna stvaranja natječu za posljednje mjesto, prolazi samo jedno. Izmjena postojeće kartice stranke ili spisa ne troši kvotu.

Rješenje. O ovim se kvotama ne pregovara, a ponavljanje zahtjeva vratit će isto odbijanje. Vratite testno okruženje na početno stanje iz svog prostora — ono ponovno kreće od demonstracijskih podataka — ili se pretplatite: ove kvote vrijede samo za testna okruženja.

Zapečaćeni spis: registar je zamrznut

Pečaćenje zamrzava lanac cjelovitosti spisa — u tome je njegova dokazna vrijednost. Zapečaćeni spis više se ne može uređivati, više ne prima dokumente i više se ne provjerava ponovno ovim kanalom. Moguća ostaje samo kvalifikacija upozorenja: ona se zapisuje izvan lanca, zapečaćeno čelo nikada se ne pomiče.

Rješenje. Nema se što „ispravljati”: to je namjerna nepromjenjivost. Ako se podaci moraju promijeniti, to je nova operacija dubinske analize u aplikaciji, a ne mutacija zapečaćenog spisa.

Zatvoren spis: poslovni odnos je završen

Odnos je zatvoren u aplikaciji: spis više ne prima zapise putem API-ja — ni uređivanje, ni dokument, ni provjeru prema popisima, ni stvarne vlasnike. Čitanje ostaje otvoreno: zatvoren spis može se pregledavati i izvoziti tijekom cijelog roka čuvanja.

Rješenje. Ponovno otvaranje poslovnog odnosa ljudski je i zabilježen postupak u aplikaciji; API to ne radi umjesto vas. Ako je operacija nova, otvorite novi spis umjesto da oživljavate stari.

Izbrisan spis: podaci su uklonjeni

Rok čuvanja je istekao i podaci spisa su izbrisani. Ostaje samo revizijski trag koji potvrđuje da je spis postojao i da je izbrisan na navedeni datum; on više ne prima nikakav zapis.

Rješenje. Nema se što ispravljati ni ponavljati: brisanje je konačno i namjerno. Identifikator izbrisanog spisa sačuvan u vašim sustavima povijest je, nikada cilj zapisa.

Format dokumenta nije prihvaćen

Popratni dokumenti prihvaćaju PDF, JPG, JPEG, PNG i WEBP — iste formate kao aplikacija. Provjerava se ekstenzija obveznog filename: dokument bez valjanog naziva datoteke odbija se, bez obzira na sadržaj.

Rješenje. Pretvorite prije slanja (TIFF ili HEIC sken pretvara se u PDF ili JPEG) i pošaljite sadržaj kao standardni base64 u contenu, s type među stabilnim kodovima a_doc_*.

Dokument veći od 6 MB

Ograničenje se odnosi na dekodiranu datoteku (6 MB), isto kao u aplikaciji i portalu za prikupljanje. Budući da base64 dodaje trećinu kodne režije, tijelo zahtjeva prihvaća do 9 MB.

Rješenje. Komprimirajte dokument (PDF skeniran u boji na 300 dpi u sivim tonovima gotovo uvijek padne ispod ograničenja) umjesto da ga dijelite.

Izvor provjere nedostupan

Nijedan subjekt iz spisa nije mogao biti provjeren prema popisima: izvor (indeks službenih popisa ili pružatelj) nije odgovorio. API odbija zaključiti — „čist” nalaz povrh mrtvog izvora bio bi najgori mogući lažno negativan rezultat. Neuspjeh se bilježi u spisu (erreurSource). Djelomičan ispad ne proizvodi ovaj 502: odgovor 200 zadržava podudaranja subjekata koji su odgovorili i imenuje neuspjele u erreurSourceEntites.

Rješenje. Ponovite isti poziv kasnije, s istim Idempotency-Key: idempotentnost pamti samo odgovore o uspjehu — ponavljanje nakon pogreške pokreće stvarnu provjeru.

Ugrađeni widgeti nisu omogućeni na ovoj instanci

Mint POST /api/v1/embed/jetons oslanja se na izvore deklarirane za vaš ured — taj popis pokreće CSP direktivu frame-ancestors ugrađenog shella. Ovaj 501 kaže da instanca koju ste pozvali ne nosi to spremište: površina za embed ondje je inertna po samoj arhitekturi, i to kaže umjesto da izda token koji nijedan izvor nikada ne bi mogao prikazati. Ne treba ga miješati sa statusom 400 koji se vraća uredu čiji izvori još nisu deklarirani.

Rješenje. Ovaj 501 govori o instanci, ne o vašem zahtjevu. Na vigilae.org administrator vašeg ureda sam deklarira izvore, na zaslonu „Integracije i sigurnost” (okvir u odjeljku o widgetima kaže gdje); zatim ponovite isti poziv. Ništa se ne mijenja u vašem kodu: zahtjev je bio ispravan, instanca nije bila spremna.

Površina nije dostupna na ovoj instalaciji

Dva osnovna čitanja — GET /api/v1/dossiers/{id}/origine-fonds i GET /api/v1/dossiers/{id}/exigences — oslanjaju se na spremišta koja ne nosi svaka instanca. Kad jedno nedostaje, API to kaže umjesto da posluži prazan popis: „nema što prijaviti” i „ništa nije pročitano” suprotne su činjenice, a njihovo brkanje učinilo bi da predmet koji nitko nije pogledao izgleda kao predmet bez primjedbi. Ovaj 501 govori o pozvanoj instanci, nikada o vašem zahtjevu ni o predmetu.

Rješenje. Ne ponavljajte poziv u petlji: ništa se neće promijeniti dok instanca ne nosi to spremište. Tretirajte kod kao „podatak ovdje nije dostupan” i osobito ga ne brojite kao nulu na svojim nadzornim pločama — tako izostanak mjerenja postaje pogrešna brojka. Na vigilae.org oba se čitanja poslužuju; na namjenskoj instalaciji nadogradnja spremišta posao je vašeg operatera.