Kiekviena klaida, paaiškinta stabiliu adresu.

Rakto nėra, jis netinkamo formato arba nežinomas

API autentifikuoja tik per antraštę Authorization: Bearer vgk_… — niekada per sesijos slapuką. Atšauktas raktas tampa nežinomas tą pačią akimirką, kai atšaukiamas.

Tas pats 401 turi "motif": "fin_option_api", kai raktas išjungtas, nes API nebėra biuro prenumeratos dalis. Šio išjungimo data buvo nurodyta el. laiške biuro administratoriams arba, jei jų nėra, biuro atsiskaitymo adresu, o vėliau skelbiama kiekvieno atsakymo į priimtą užklausą antraštėje Sunset (tvarkaraštis: #cle-expiree). Be motyvo jis taip pat gali kilti dėl sustabdytos prenumeratos: sustabdymas raktus nutraukia iš karto.

Ką daryti. Patikrinkite, ar antraštė iš tiesų išsiunčiama (tarpiniai serveriai kartais ją nukerpa), ar raktas prasideda vgk_ ir ar jis nebuvo atšauktas iš biuro konsolės. Kadangi paslaptis parodoma tik kuriant, pamestas raktas keičiamas nauju, o ne atkuriamas. Kai atsakyme yra "motif": "fin_option_api", nekalta nei antraštė, nei raktas: biuro administratorius parašo mums adresu contact@vigilae.org, kad API būtų grąžinta į prenumeratą, ir tas pats raktas vėl priimamas, kai tik tai padaroma, iki jo paties galiojimo pabaigos.

Pasibaigusio galiojimo raktas

Kiekvieno rakto galiojimas baigiasi po metų nuo sukūrimo — data expire_le biuro konsolėje matoma nuo pirmos dienos. Galiojimo pabaigos 401 yra aiškus: jis sako, kad raktas egzistavo ir nebegalioja.

API raktas gali nustoti būti priimamas ir prieš šią datą, kai API nebėra biuro prenumeratos dalis. Tada jis išjungiamas ne anksčiau kaip po 30 dienų nuo pirmojo el. laiško, tą dieną, kurią nurodo antrasis el. laiškas, išsiųstas ne vėliau kaip prieš 7 dienas; abu siunčiami biuro administratoriams arba, jei jų nėra, biuro atsiskaitymo adresu. Kai tik ši data nustatoma, ji matoma biuro konsolėje (GET /connect/cles laukas coupure_le), o kiekvienas atsakymas į priimtą užklausą ją skelbia antraštėje Sunset, kol ji ateina. Po šios datos užklausa gauna 401, aprašytą skyriuje #authentification, su "motif": "fin_option_api"; jei API vėl įtraukiama į prenumeratą, raktas vėl priimamas, iki jo paties galiojimo pabaigos.

Ką daryti. Sukurkite naują raktą, perjunkite į jį savo iškvietimus, atšaukite senąjį. API raktui reikia, kad API vis dar būtų biuro prenumeratos dalis: be jos konsolė atsisako sukurti raktą. Šį pakeitimą planuokite savo operacijose, o ne atraskite netikėtai.

Nepakankama aprėptis

Raktai turi aprėptis, pažymėtas juos kuriant: bendrąsias lecture (skaitymas, numatytoji) ir ecriture (rašymas) arba smulkias pagal išteklių (clients:lecture, pieces:ecriture, origine-fonds:lecture, journal:lecture…).

Paveldėjimas remiasi priesaga ir veikia tik viena kryptimi: lecture apima kiekvieną *:lecture, ecriture — kiekvieną *:ecriture; atvirkščiai — niekada, smulki aprėptis atveria tik save.

Šešios aprėptys iškrenta iš šios poros ir nepaveldimos iš jokio bendrojo rakto: alertes:qualifier, embed:emettre, adversemedia:consulter, conformite:consulter, dispositif:consulter, integrite:consulter. Įvykio kvalifikavimas, įterpimo prieigos rakto išdavimas, bylos nepalankios spaudos ar bylos tvarkymo įvertinimo skaitymas niekada neišplaukia iš bendrosios skaitymo teisės: kiekviena žymima atskirai.

Ką daryti. Sukurkite raktą su reikiama aprėptimi — ir tik su ja. Mažiausios privilegijos čia sąmoningos: integracija, kuri tik skaito, neturi jokios priežasties laikyti rašymo rakto, o platus raktas niekada neatstos aprėpties, kuri nebuvo aiškiai deleguota.

Nerasta — arba priklauso kitam biurui

404 reiškia, kad išteklius neegzistuoja arba priklauso kitam biurui. API šių dviejų atvejų niekada neskiria: skirti reikštų atskleisti, kas egzistuoja kitur. Atskyrimas užtikrinamas duomenų bazės lygmeniu, ne vien programos kode.

Ką daryti. Patikrinkite seq pagal to biuro, kuriam priklauso raktas, žurnalą (GET /api/v1/evenements). Jei integruojate kelis biurus, kiekvienas biuras turi savus raktus: seq tarp biurų nekeliauja.

Ši paskyra jau yra

POST /scim/v2/Users į šiai kontorai jau sukurtą userName atsako 409 su scimType: uniqueness. Unikalumą laiko duomenų bazės apribojimas, o ne podėlis: du vienalaikiai kūrimai negali sukurti dviejų paskyrų.

Ką daryti. Vertinkite 409 kaip idempotentinę sėkmę, o ne klaidą: perskaitykite paskyrą su ?filter=userName eq "…" ir tęskite su grąžintu identifikatoriumi. Jungtis, kuri po 409 kartoja cikle, niekada nesukurs nieko daugiau.

Ši paskyra nepasiekiama katalogui

Katalogas negali nei pažeminti, nei išjungti paskyros, turinčios kontoros administravimo galias: prašymas atmetamas su scimType: mutability ir įrašomas į žurnalą. Be šios ribos jungtis, perėmusi už atitiktį atsakingo asmens adresą, uždarytų kontorą būtent tam, kuris už ją atsako.

Ką daryti. Pašalinkite šį asmenį iš sinchronizuojamos apimties arba pakeiskite jo vaidmenį pačioje Vigilae. Atmetimas liečia tik šią paskyrą: likusi partijos dalis taikoma įprastai.

Viršyta užklausų sparta

60 užklausų per minutę vienam raktui pagal numatytuosius nustatymus (galima keisti kiekvienam raktui atskirai). Atsakymas neša Retry-After ir antraštes X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.

Ką daryti. Gerbkite Retry-After — jokio kartojimo iškart. Į ribą atsitrenkiama apklausiant beveik visada dėl pilno pernuskaitymo: žymeklis depuisSeq niekada neskaito iš naujo to, kas jau perskaityta.

Parašas jūsų pusėje nepasitvirtina

Jūsų gavėjas privalo perskaičiuoti v1 = HMAC-SHA256(secret, t + "." + body) iš gauto neapdoroto kūno ir atmesti bet kokį t, senesnį nei 5 min. Klasikiniai nesklandumai: kūnas prieš tikrinimą serializuotas iš naujo (performatuotas JSON nebeturi tų pačių baitų), laikrodis, nuslinkęs už tolerancijos ribos, ir ignoruota rotacija — 24 val. antraštėje yra po vieną v1 kiekvienai dar galiojančiai paslapčiai, ir priimti privalote, jei sutampa bent viena.

Ką daryti. Tikrinkite pagal neapdorotus baitus, sinchronizuokite laikrodį (NTP), išbandykite savo tikrinimą rotacijos metu. Node ir Python fragmentai dokumentacijoje daro būtent tai — kopijuokite juos, užuot rašę iš naujo.

Įvykis atkeliauja du kartus

Pristatymas yra at-least-once, paketais ne didesniais kaip 100, žurnalo tvarka; žymeklis pasislenka tik gavus jūsų 2xx, paketas po paketo. Gedimas po gavimo, bet prieš žymekliui pasislenkant, sukelia pakartotinį pristatymą — tai kontraktas, o ne defektas.

Ką daryti. seq yra jūsų idempotencijos raktas: kiekvieną seką apdorokite lygiai vieną kartą ir 2xx atsakykite tik įrašę į saugyklą. Per ankstyvas 2xx ir po jo įvykęs strigimas — vienintelis būdas prarasti įvykį.

Žurnalas atrodo neišsamus arba kartojasi

depuisSeq yra griežtai išskirtinis: grąžinami tik įvykiai su didesniu seq, surikiuoti didėjančia tvarka, ne daugiau kaip 500 puslapyje. Atsakymas grąžina prochainSeq, kurį perduodate nepakeistą. Puslapis, trumpesnis už limite, reiškia žurnalo pabaigą.

Ką daryti. Saugokite prochainSeq tarp paleidimų ir niekada neperskaičiuokite jo patys. Dublikatai reiškia, kad startavote nuo per seno žymeklio; spragos — kad praleidote nepavykusį puslapį jo nepakartoję.

Parametras už schemos ribų

Nežinoma būsena, sprendimas ne iš sąrašo (planifie, traite, ecarte), nesveikaskaitinis limite: atsakymas įvardija netinkamą lauką ir nieko daugiau — klaidų pranešimai niekada neneša bylų turinio.

Ką daryti. OpenAPI specifikacija yra šaltinis: jos deklaruojami išvardijimai ir ribos yra tie patys, kuriuos taiko serveris, nes ją pateikia jis pats.

Laukas, kurio reikšmė per ilga: Pilietybė

Atsakymas įvardija netinkamą lauką ir nieko daugiau — klaidų pranešimai niekada neneša bylų turinio.

Ką daryti. OpenAPI specifikacija yra šaltinis: jos deklaruojami išvardijimai ir ribos yra tie patys, kuriuos taiko serveris, nes ją pateikia jis pats.

Nepakankama aprėptis (išteklių API)

Išteklių galiniams taškams (/clients, /dossiers, dokumentai, patikra, įspėjimai) reikia smulkiosios aprėpties: clients:*, dossiers:*, pieces:*, criblage:* arba skirtosios aprėpties alertes:qualifier. Senasis raktas lecture suteikia visas *:lecture aprėptis, o ecriture — visas *:ecriture, tačiau alertes:qualifier niekada nepaveldima: įspėjimo kvalifikavimas yra atsakingo asmens veiksmas, deleguojamas pažymint šią aprėptį kuriant raktą.

Ką daryti. Sukurkite raktą tiksliai su tomis aprėptimis, kurių reikia jūsų integracijai — ir tik su jomis. Atsakymo detail įvardija trūkstamą aprėptį.

Išteklius nerastas — arba priklauso kitam biurui

Ta pati taisyklė kaip #cloisonnement, taikoma ištekliams: klientas, byla, dokumentas ar įspėjimas, kuris neegzistuoja arba priklauso kitam biurui, gauna tą patį 404. API šių dviejų atvejų niekada neskiria.

Ką daryti. Patikrinkite identifikatorių pagal to biuro, kuriam priklauso raktas, sąrašus. Identifikatorius niekada nekeliauja iš vieno biuro į kitą.

Trūksta Idempotency-Key antraštės

Kiekvienam kuriančiam ar paleidžiančiam POST (klientas, byla, dokumentas, patikra, tikrieji savininkai) reikia antraštės Idempotency-Key: stabili eilutė, ne ilgesnė kaip 200 ženklų, po vieną kiekvienai operacijai. Pakartojus tą patį raktą su tuo pačiu kūnu, grąžinamas tas pats atsakymas be jokio poveikio — jūsų apsauga nuo dublikatų per tinklo incidentą.

Ką daryti. Sugeneruokite raktą prieš pirmą bandymą (po vieną UUID kiekvienai verslo operacijai) ir naudokite jį nepakeistą kiekvienam tos pačios operacijos pakartojimui.

Idempotencijos raktas pakartotas su kitu kūnu

Šis Idempotency-Key per pastarąsias 24 valandas jau buvo panaudotas kitam kūnui. Raktas pakartoja atsakymą, jis niekada jo neperrašo: jo naudojimas naujai operacijai beveik visada rodo raktą, išvestą iš skaitiklio ar nukirstos datos.

Ką daryti. Naujas raktas kiekvienai naujai operacijai. Niekada neveskite rakto iš duomenų, kurie tarp operacijų kartojasi.

Kitas bandymas su tuo pačiu raktu dar vykdomas

Dvi užklausos su tuo pačiu Idempotency-Key atėjo kartu: pirmoji vykdoma, antroji atmetama prieš bet kokį poveikį. Būtent šis atmetimas neleidžia atsirasti dublikatui. Įprastas atvejis: tarpinis serveris grąžina 502 arba 504, kol serveris dar dirba, ir jūsų klientas užklausą pakartoja. Antraštė Retry-After nurodo, po kelių sekundžių ją pakartoti.

Ką daryti. Pakartokite tą pačią užklausą be pakeitimų, su tuo pačiu raktu, pasibaigus nurodytam laukimui: gausite pirmojo bandymo atsakymą. Niekada nekurkite naujo rakto, kad „atblokuotumėte“ — taip sukurtumėte būtent tą dublikatą, kurio raktas išvengia.

Testavimo aplinka: kvota išnaudota

Testavimo aplinkoje galioja fiksuotos ribos: 200 klientų kortelių, 50 bylų ir 40 dokumentų vienai bylai. Kūrimas ar įkėlimas, kuris viršytų bet kurią iš jų, atmetamas prieš bet kokį įrašymą, o atmetimas parodo, kuri riba pasiekta: laukuose ressource, quota ir courant nurodomi išteklius, viršutinė riba ir kiekis atmetimo metu. Jei du vienalaikiai kūrimai varžosi dėl paskutinės vietos, praleidžiamas tik vienas. Esamos kliento kortelės ar bylos redagavimas kvotos neeikvoja.

Ką daryti. Dėl šių kvotų nesiderama, o pakartojus užklausą grąžinamas tas pats atmetimas. Atkurkite pradinę testavimo aplinkos būseną iš savo darbo srities — ji vėl prasideda nuo demonstracinių duomenų — arba užsisakykite prenumeratą: šios kvotos taikomos tik testavimo aplinkoms.

Užantspauduota byla: registras įšaldytas

Antspaudavimas įšaldo bylos vientisumo grandinę — būtent tai yra jos įrodomoji vertė. Užantspauduotos bylos nebegalima redaguoti, ji nebepriima dokumentų ir šiuo kanalu nebetikrinama pakartotinai. Lieka galimas tik įspėjimų kvalifikavimas: jis rašomas šalia grandinės, užantspauduota viršūnė niekada nejuda.

Ką daryti. Nėra ko „taisyti“: tai sąmoningas nekintamumas. Jei duomenys turi keistis, tai nauja deramo patikrinimo operacija programoje, o ne užantspauduotos bylos mutacija.

Uždaryta byla: dalykiniai santykiai užbaigti

Santykiai užbaigti programoje: byla per API nebepriima įrašų — nei redagavimo, nei dokumento, nei patikros, nei tikrųjų savininkų. Skaitymas lieka atviras: uždarytą bylą galima peržiūrėti ir eksportuoti visą saugojimo laiką.

Ką daryti. Santykių atnaujinimas yra žmogaus veiksmas, registruojamas programoje; API to už jus nepadarys. Jei operacija nauja, atverkite naują bylą, o ne gaivinkite senosios.

Pašalinta byla: duomenys ištrinti

Saugojimo terminas pasibaigė ir bylos duomenys ištrinti. Lieka tik audito žymė, kuri patvirtina, kad byla buvo ir kad nurodytą dieną ji pašalinta; ji nebepriima jokio įrašo.

Ką daryti. Nėra ko taisyti ir ko kartoti: ištrynimas yra galutinis ir sąmoningas. Jūsų sistemose išsaugotas pašalintos bylos identifikatorius yra istorija, o ne įrašymo tikslas.

Nepriimtinas dokumento formatas

Patvirtinamieji dokumentai priimami PDF, JPG, JPEG, PNG ir WEBP formatais — tais pačiais kaip programoje. Tikrinamas privalomo filename plėtinys: dokumentas be tinkamo failo vardo atmetamas, kad ir koks būtų jo turinys.

Ką daryti. Konvertuokite prieš siųsdami (TIFF ar HEIC skenas konvertuojasi į PDF ar JPEG) ir siųskite turinį standartiniu base64 lauke contenu, su type iš stabilių a_doc_* kodų.

Dokumentas didesnis nei 6 MB

Riba taikoma dekoduotam failui (6 MB) — ta pati kaip programoje ir dokumentų surinkimo portale. Kadangi base64 prideda trečdalį kodavimo antsvorio, užklausos kūnas priima iki 9 MB.

Ką daryti. Suglaudinkite dokumentą (spalvotas 300 dpi skenuotas PDF pilkų tonų režimu beveik visada nusileidžia žemiau ribos), užuot jį skaidę.

Patikros šaltinis nepasiekiamas

Nė vieno bylos subjekto nepavyko sutikrinti su sąrašais: šaltinis (oficialių sąrašų indeksas arba tiekėjas) neatsakė. API atsisako daryti išvadą — „švari“ ataskaita ant mirusio šaltinio būtų pats blogiausias įmanomas klaidingai neigiamas rezultatas. Gedimas užfiksuojamas byloje (erreurSource). Dalinis sutrikimas šio 502 nesukelia: 200 atsakymas išsaugo atsakiusių subjektų atitikmenis, o neatsakiusius įvardija lauke erreurSourceEntites.

Ką daryti. Vėliau pakartokite tą patį iškvietimą su ta pačia Idempotency-Key: idempotencija įsimena tik sėkmės atsakymus — pakartojimas po klaidos paleidžia tikrą patikrą.

Įterptieji valdikliai neįjungti šioje instancijoje

Ženklų išdavimo užklausa POST /api/v1/embed/jetons remiasi jūsų biurui deklaruotomis kilmėmis — būtent šis sąrašas valdo įterptojo apvalkalo frame-ancestors CSP. Šis 501 sako, kad jūsų iškviesta instancija neturi šios saugyklos: įterpimo paviršius joje inertiškas pagal konstrukciją, ir tai pasako, užuot išdavęs ženklą, kurio nė viena kilmė niekada negalėtų atvaizduoti. Nepainiokite su 400, grąžinamu biurui, kurio kilmės dar nedeklaruotos.

Ką daryti. Šis 501 kalba apie instanciją, ne apie jūsų užklausą. Svetainėje vigilae.org jūsų biuro administratorius pats deklaruoja kilmes ekrane „Integracijos ir saugumas“ (kur — nurodo valdiklių skyriaus langelis); tada pakartokite tą pačią užklausą. Kode nieko keisti nereikia: užklausa buvo tvarkinga, instancija — dar neparuošta.

Paviršius nepasiekiamas šiame diegime

Du pamatiniai skaitymai — GET /api/v1/dossiers/{id}/origine-fonds ir GET /api/v1/dossiers/{id}/exigences — remiasi saugyklomis, kurių turi ne kiekvienas egzempliorius. Kai vienos trūksta, API tai pasako, o ne pateikia tuščią sąrašą: „nėra ko pranešti“ ir „niekas nebuvo perskaityta“ yra priešingi faktai, o juos supainiojus byla, į kurią niekas nepažvelgė, atrodytų kaip byla be pastabų. Šis 501 kalba apie iškviestą egzempliorių, niekada apie jūsų užklausą ar bylą.

Ką daryti. Nekartokite kvietimo cikle: niekas nepasikeis, kol egzempliorius neturės tos saugyklos. Traktuokite šį kodą kaip „duomenų čia nėra“ ir svarbiausia neskaičiuokite jo kaip nulio savo skydeliuose — būtent taip trūkstamas matavimas virsta klaidingu skaičiumi. Svetainėje vigilae.org abu skaitymai aptarnaujami; specialiame diegime saugyklos atnaujinimas tenka jūsų operatoriui.