Svaka pogreška, objašnjena na stabilnoj adresi.
Ova stranica je operativna referenca, ne prodajni govor. Svaka klasa pogrešaka Connect API-ja ovdje ima trajno sidro; odgovori API-ja s pogreškom upućivat će na te adrese. Dobivate vjerojatni uzrok i rješenje — tim redom. Natrag na dokumentaciju za programere.
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.
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.
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.
Rješenje. Stvorite novi ključ, prebacite svoje pozive, opozovite stari. Zamjenu uvrstite u svoje operativne planove umjesto da je otkrivate: datum je poznat godinu dana unaprijed.
Nedovoljan opseg
Ključevi nose lecture (čitanje, zadano) i/ili ecriture (pisanje). Kvalificiranje događaja zahtijeva ecriture; ključ samo za čitanje dobiva 403 bez obzira na resurs.
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.
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.
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.
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.
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.
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.
Ova stranica razvijat će se s API-jem; postojeća sidra, međutim, nikada ne mijenjaju adresu — možete ih pohraniti u svoje operativne zapisnike.