Vsaka napaka, pojasnjena na stalnem naslovu.

Ključ manjka, je napačno oblikovan ali neznan

API avtenticira izključno prek glave Authorization: Bearer vgk_… — nikoli prek sejnega piškotka. Preklican ključ postane neznan v trenutku preklica.

Isti 401 nosi "motif": "fin_option_api", kadar je bil ključ ustavljen, ker API ni več del naročnine pisarne. Datum te ustavitve je bil naveden v e-poštnem sporočilu skrbnikom pisarne ali, če jih ni, na naslov za račune pisarne, nato pa napovedan v glavi Sunset vsakega odgovora na sprejet klic (časovnica v #cle-expiree). Brez motiva lahko izvira tudi iz začasno ustavljene naročnine: začasna ustavitev ključe takoj prekine.

Popravek. Preverite, da glava dejansko odide (posredniki jo včasih odstranijo), da se ključ začne z vgk_ in da ni bil preklican iz konzole pisarne. Ker se skrivnost prikaže le ob ustvarjanju, se izgubljen ključ zamenja, ne obnovi. Pri "motif": "fin_option_api" napaka ni ne v glavi ne v ključu: skrbnik pisarne nam piše na contact@vigilae.org, da se API vrne v naročnino, in isti ključ znova velja, takoj ko je to storjeno, do izteka lastne veljavnosti.

Potekli ključ

Vsak ključ poteče eno leto po ustvarjanju — datum expire_le je v konzoli pisarne viden od prvega dne. 401 ob poteku je izrecen: pove, da je ključ obstajal in ni več veljaven.

API ključ lahko preneha veljati tudi pred tem datumom, kadar API ni več del naročnine pisarne. Ustavitev tedaj nastopi najmanj 30 dni po prvem e-poštnem sporočilu, na datum, ki ga navede drugo sporočilo, poslano najmanj 7 dni vnaprej; obe sta namenjeni skrbnikom pisarne ali, če jih ni, na naslov za račune pisarne. Ko je ta datum določen, je viden v konzoli pisarne (polje coupure_le v GET /connect/cles), vsak odgovor na sprejet klic pa ga napoveduje v glavi Sunset, dokler ne nastopi. Po tem datumu klic prejme 401, opisan v #authentification, z "motif": "fin_option_api"; če se API vrne v naročnino, ključ znova velja, do izteka lastne veljavnosti.

Popravek. Ustvarite nov ključ, nanj preusmerite svoje klice, starega prekličite. Za API ključ mora biti API še vedno del naročnine pisarne: brez njega konzola zavrne ustvarjanje ključa. To zamenjavo načrtujte v svojih operacijah, namesto da jo odkrijete.

Nezadosten obseg

Ključi nosijo obsege, označene ob njihovem ustvarjanju: splošna lecture (branje, privzeto) in ecriture (pisanje) ali drobne po virih (clients:lecture, pieces:ecriture, origine-fonds:lecture, journal:lecture…).

Dedovanje sledi priponi, le v eno smer: lecture pokriva vsak *:lecture, ecriture vsak *:ecriture — obratno nikoli; droben obseg odpre le sebe.

Šest obsegov izpade iz tega para in se ne deduje iz nobenega splošnega ključa: alertes:qualifier, embed:emettre, adversemedia:consulter, conformite:consulter, dispositif:consulter, integrite:consulter. Kvalificiranje dogodka, izdaja žetona za vgradnjo, branje neugodnega tiska ob spisu ali ocene vodenja spisa nikoli ne izhaja iz splošne pravice do branja: vsak se označi posebej.

Popravek. Ustvarite ključ z zahtevanim obsegom — in samo z njim. Najmanjši privilegij je nameren: integracija, ki samo bere, nima razloga, da bi imela ključ za pisanje, širok ključ pa nikoli ne nadomesti obsega, ki ni bil izrecno dodeljen.

Ni najdeno — ali pripada drugi pisarni

404 pomeni, da vir ne obstaja ali pripada drugi pisarni. API teh dveh primerov nikoli ne razlikuje: razlikovanje bi razkrilo, kaj obstaja drugje. Ločevanje se uveljavlja na ravni podatkovne baze, ne le v aplikacijski kodi.

Popravek. Preverite seq glede na dnevnik pisarne, ki ji ključ pripada (GET /api/v1/evenements). Če integrirate več pisarn, ima vsaka pisarna svoje ključe: seq ne potuje med pisarnami.

Ta račun že obstaja

POST /scim/v2/Users na userName, ki je za to pisarno že ustvarjen, odgovori s 409 in scimType: uniqueness. Enkratnost drži omejitev zbirke podatkov, ne predpomnilnik: dve hkratni stvaritvi ne moreta ustvariti dveh računov.

Popravek. 409 obravnavajte kot idempotenten uspeh, ne kot napako: račun preberite z ?filter=userName eq "…" in nadaljujte z vrnjenim identifikatorjem. Priključek, ki po 409 ponavlja v zanki, ne bo nikoli ustvaril ničesar več.

Ta račun je zunaj dosega imenika

Imenik računa s pooblastili za upravljanje pisarne ne more niti degradirati niti onemogočiti: zahteva se zavrne z scimType: mutability in zabeleži. Brez te meje bi priključek, ki prevzame naslov osebe, odgovorne za skladnost, zaprl pisarno prav tistemu, ki zanjo odgovarja.

Popravek. To osebo odstranite iz usklajevanega obsega ali ji spremenite vlogo znotraj Vigilae. Zavrnitev velja le za ta račun: preostanek svežnja se uporabi običajno.

Presežena omejitev zahtev

60 zahtev na minuto na ključ, privzeto (nastavljivo po ključu). Odgovor nosi Retry-After in glave X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.

Popravek. Upoštevajte Retry-After — brez takojšnjega ponovnega poskusa. Zadeti omejitev med poizvedovanjem je skoraj vedno znak polnega ponovnega branja: kazalec depuisSeq nikoli znova ne prebere že prebranega.

Podpis se na vaši strani ne preveri uspešno

Vaš prejemnik mora znova izračunati v1 = HMAC-SHA256(secret, t + "." + body) iz surovega prejetega telesa in zavrniti vsak t, starejši od 5 min. Klasične napake: telo, ponovno serializirano pred preverjanjem (preoblikovan JSON nima več istih bajtov), ura, ki uide izven tolerance, in prezrta rotacija — 24 ur glava nosi po en v1 za vsako še veljavno skrivnost, sprejeti pa morate, če se ujema katera koli.

Popravek. Preverjajte na surovih bajtih, sinhronizirajte uro (NTP), preizkusite svoje preverjanje med rotacijo. Odlomka Node in Python v dokumentaciji počneta natanko to — raje ju prekopirajte, kot da ju pišete na novo.

Dogodek prispe dvakrat

Dostava je at-least-once, v paketih po največ 100, po vrstnem redu dnevnika; kazalec napreduje šele ob vašem 2xx, paket za paketom. Napaka po prejemu, a pred napredovanjem kazalca, povzroči ponovno dostavo — to je pogodba, ne okvara.

Popravek. seq je vaš idempotentni ključ: vsako zaporedje obdelajte natanko enkrat in z 2xx odgovorite šele po trajnem zapisu. Prezgodnji 2xx, ki mu sledi sesutje, je edini način, da dogodek izgubite.

Dnevnik je videti nepopoln ali se ponavlja

depuisSeq je strogo izključujoč: vrnjeni so le dogodki z višjim seq, urejeni naraščajoče, največ 500 na stran. Odgovor vrne prochainSeq, ki ga podate nespremenjenega. Stran, krajša od limite, pomeni konec dnevnika.

Popravek. prochainSeq trajno shranjujte med zagoni in ga nikoli ne izračunavajte sami. Podvojitve pomenijo, da ste znova začeli s prestarim kazalcem; vrzeli pomenijo, da ste preskočili neuspelo stran, ne da bi jo ponovili.

Parameter izven sheme

Neznan status, razrešitev izven seznama (planifie, traite, ecarte), neceloštevilski limite: odgovor imenuje sporno polje in nič drugega — sporočila o napakah nikoli ne nosijo vsebine zadev.

Popravek. Specifikacija OpenAPI je vir: naštevanja in meje, ki jih deklarira, so tiste, ki jih strežnik uveljavlja, saj jo streže sam.

Polje, katerega vrednost je predolga: Državljanstvo

Odgovor imenuje sporno polje in nič drugega — sporočila o napakah nikoli ne nosijo vsebine zadev.

Popravek. Specifikacija OpenAPI je vir: naštevanja in meje, ki jih deklarira, so tiste, ki jih strežnik uveljavlja, saj jo streže sam.

Nezadosten obseg (API virov)

Končne točke virov (/clients, /dossiers, listine, pregledovanje, opozorila) zahtevajo drobnozrnat obseg: clients:*, dossiers:*, pieces:*, criblage:* ali namenski obseg alertes:qualifier. Podedovani ključ lecture podeli vse obsege *:lecture, ecriture pa vse *:ecriture — a alertes:qualifier se nikoli ne deduje: kvalificiranje opozorila je dejanje odgovorne osebe, ki se prenese tako, da ta obseg označite ob ustvarjanju ključa.

Popravek. Ustvarite ključ z natanko tistimi obsegi, ki jih vaša integracija potrebuje — in samo z njimi. Polje detail v odgovoru imenuje manjkajoči obseg.

Vir ni najden — ali pripada drugi pisarni

Enako pravilo kot #cloisonnement, uporabljeno na virih: stranka, zadeva, listina ali opozorilo, ki ne obstaja ali pripada drugi pisarni, dobi isti 404. API teh dveh primerov nikoli ne loči.

Popravek. Preverite identifikator glede na sezname pisarne, ki ji ključ pripada. Identifikator nikoli ne potuje iz ene pisarne v drugo.

Manjka glava Idempotency-Key

Vsak POST za ustvarjanje ali proženje (stranka, zadeva, listina, pregledovanje, dejanski lastniki) zahteva glavo Idempotency-Key: stabilen niz z največ 200 znaki, po eden na operacijo. Ponovitev istega ključa z istim telesom vrne isti odgovor, brez učinka — vaša zaščita pred podvojitvami ob omrežnem incidentu.

Popravek. Ključ ustvarite pred prvim poskusom (en UUID na poslovno operacijo) in ga nespremenjenega uporabite pri vsakem ponovnem poskusu te iste operacije.

Idempotentni ključ ponovno uporabljen z drugačnim telesom

Ta Idempotency-Key je bil v zadnjih 24 urah že uporabljen za drugačno telo. Ključ ponovi odgovor, nikoli ga ne prepiše: njegova ponovna uporaba za novo operacijo je skoraj vedno znak ključa, izpeljanega iz števca ali okrnjenega datuma.

Popravek. Nov ključ za vsako novo operacijo. Ključa nikoli ne izpeljujte iz podatkov, ki se med operacijami ponavljajo.

Drug poskus s tem ključem še poteka

Dve zahtevi z istim Idempotency-Key sta prispeli skupaj: prva se izvede, druga je zavrnjena pred vsakim učinkom. Prav ta zavrnitev prepreči podvojitev. Običajen primer: posredniški strežnik vrne 502 ali 504, medtem ko strežnik še dela, in vaš odjemalec zahtevo ponovi. Glava Retry-After pove, po koliko sekundah jo ponoviti.

Popravek. Ponovite isto zahtevo nespremenjeno, z istim ključem, po napovedanem čakanju: prejeli boste odgovor prvega poskusa. Nikoli ne ustvarjajte novega ključa, da bi »sprostili« — s tem bi ustvarili prav tisto podvojitev, ki jo ključ preprečuje.

Testno okolje: kvota dosežena

Testno okolje ima stalne omejitve: 200 kartic strank, 50 zadev in 40 listin na zadevo. Ustvarjanje ali nalaganje, ki bi preseglo katero od njih, je zavrnjeno pred vsakim zapisom, zavrnitev pa pove, katero: polja ressource, quota in courant navajajo vir, zgornjo mejo in število ob zavrnitvi. Od dveh hkratnih stvaritev za zadnje prosto mesto uspe le ena. Urejanje obstoječe kartice ali zadeve ne porabi ničesar.

Popravek. O teh kvotah se ni mogoče pogajati, ponovitev zahteve pa bo vrnila isto zavrnitev. Testno okolje ponastavite v svojem prostoru — znova začne s predstavitvenimi podatki — ali sklenite naročnino: te kvote veljajo samo za testna okolja.

Zapečatena zadeva: register je zamrznjen

Pečatenje zamrzne verigo celovitosti zadeve — v tem je njena dokazna vrednost. Zapečatene zadeve ni več mogoče urejati, ne sprejema več listin in se po tem kanalu ne pregleduje več znova. Mogoča ostane le kvalifikacija opozoril: zapiše se zunaj verige, zapečatena glava se nikoli ne premakne.

Popravek. Ničesar ni treba »popraviti«: to je namerna nespremenljivost. Če se morajo podatki spremeniti, je to nova operacija skrbnega pregleda v aplikaciji, ne mutacija zapečatene zadeve.

Zaprta zadeva: poslovno razmerje je končano

Razmerje je bilo zaprto v aplikaciji: zadeva prek API ne sprejema več zapisov — ne urejanja, ne listine, ne pregledovanja, ne dejanskih lastnikov. Branje ostaja odprto: zaprto zadevo je mogoče ves čas hrambe pregledovati in izvažati.

Popravek. Ponovno odprtje razmerja je človeško in zabeleženo dejanje v aplikaciji; API tega ne stori namesto vas. Če je operacija nova, odprite novo zadevo, namesto da obujate staro.

Izbrisana zadeva: podatki so odstranjeni

Rok hrambe je potekel in podatki zadeve so izbrisani. Ostane le revizijska sled, ki potrjuje, da je zadeva obstajala in da je bila na navedeni datum izbrisana; ta ne sprejema več nobenega zapisa.

Popravek. Ničesar ni treba popraviti ali ponoviti: izbris je dokončen in nameren. Identifikator izbrisane zadeve, shranjen v vaših sistemih, je zgodovina, nikoli cilj zapisa.

Format listine ni sprejet

Dokazila sprejemajo PDF, JPG, JPEG, PNG in WEBP — iste formate kot aplikacija. Preverjanje poteka na končnici obveznega polja filename: listina brez veljavnega imena datoteke je zavrnjena, ne glede na vsebino.

Popravek. Pretvorite pred pošiljanjem (sken TIFF ali HEIC se pretvori v PDF ali JPEG) in vsebino pošljite kot standardni base64 v polju contenu, s type med stabilnimi kodami a_doc_*.

Listina nad 6 MB

Omejitev velja za dekodirano datoteko (6 MB), enako kot v aplikaciji in na portalu za zbiranje. Ker base64 doda tretjino kodirne režije, telo zahteve sprejme do 9 MB.

Popravek. Listino raje stisnite (barvni PDF, skeniran pri 300 dpi, v sivinah skoraj vedno pade pod omejitev), kot da jo razdelite.

Vir pregledovanja ni na voljo

Nobenega subjekta zadeve ni bilo mogoče preveriti po seznamih: vir (indeks uradnih seznamov ali ponudnik) ni odgovoril. API zavrača sklepanje — »čisto« poročilo na mrtvem viru bi bil najhujši možni lažni negativni izid. Napaka se zabeleži na zadevi (erreurSource). Delni izpad ne povzroči tega 502: odgovor 200 obdrži zadetke subjektov, ki so odgovorili, in v erreurSourceEntites imenuje tiste, ki so odpovedali.

Popravek. Pozneje ponovite isti klic, z isto Idempotency-Key: idempotentnost si zapomni samo odgovore o uspehu — ponovitev po napaki izvede resnično pregledovanje.

Vgrajeni gradniki niso omogočeni na tej instanci

Izdaja žetona POST /api/v1/embed/jetons se opira na izvore, navedene za vašo pisarno — prav ta seznam poganja CSP direktivo frame-ancestors vgrajene lupine. Ta 501 pove, da klicana instanca ne nosi te shrambe: površina za vgrajene gradnike je tam po zasnovi neaktivna in to pove, namesto da bi izdala žeton, ki ga noben izvor ne bi mogel nikoli prikazati. Ne zamenjujte s 400, ki se vrne pisarni, katere izvori še niso navedeni.

Popravek. Ta 501 govori o instanci, ne o vaši zahtevi. Na vigilae.org administrator vaše pisarne izvore navede sam, na zaslonu »Integracije in varnost« (okvir v razdelku o gradnikih pove, kje); nato ponovite isti klic. V vaši kodi ni treba nič spremeniti: zahteva je bila v redu, instanca pa ni bila pripravljena.

Površina v tej namestitvi ni na voljo

Dve temeljni branji — GET /api/v1/dossiers/{id}/origine-fonds in GET /api/v1/dossiers/{id}/exigences — se opirata na shrambe, ki jih ne nosi vsak izvod. Kadar katera manjka, API to pove, namesto da bi postregel prazen seznam: „ni česa poročati“ in „nič ni bilo prebrano“ sta nasprotni dejstvi, njuno mešanje pa bi spis, ki ga ni nihče pogledal, prikazalo kot spis brez pripomb. Ta 501 govori o klicanem izvodu, nikoli o vaši zahtevi ali o spisu.

Popravek. Klica ne ponavljajte v zanki: nič se ne bo spremenilo, dokler izvod ne nosi te shrambe. Kodo obravnavajte kot „podatek tu ni na voljo“ in je predvsem ne štejte kot nič na svojih nadzornih ploščah — prav tako manjkajoča meritev postane napačna številka. Na vigilae.org sta obe branji postreženi; pri namenski namestitvi je nadgradnja shrambe stvar vašega upravljavca.