Kull żball, spjegat f'indirizz stabbli.

Ċavetta nieqsa, malformata jew mhux magħrufa

L-API tawtentika esklussivament permezz tal-header Authorization: Bearer vgk_… — qatt permezz ta' cookie tas-sessjoni. Ċavetta revokata ssir mhux magħrufa fil-mument stess li tiġi revokata.

L-istess 401 iġorr "motif": "fin_option_api" meta ċ-ċavetta twaqqfet għax l-API m'għadhiex parti mill-abbonament tal-uffiċċju. Id-data ta' dan il-waqfien ingħatat f'email lill-amministraturi tal-uffiċċju jew, fin-nuqqas tagħhom, lill-indirizz tal-fatturazzjoni tal-uffiċċju, u mbagħad tħabbret fil-header Sunset ta' kull tweġiba għal sejħa aċċettata (l-iskeda taħt #cle-expiree). Mingħajr motiv, jista' jiġi wkoll minn abbonament sospiż: is-sospensjoni taqta' ċ-ċwievet minnufih.

Ir-rimedju. Iċċekkja li l-header verament jitlaq (il-proxies xi drabi jneħħuh), li ċ-ċavetta tibda b'vgk_ u li ma ġietx revokata mill-console tal-uffiċċju. Peress li s-sigriet jintwera biss mal-ħolqien, ċavetta mitlufa tinbidel, ma tiġix irkuprata. Bi "motif": "fin_option_api", la l-header u lanqas iċ-ċavetta mhuma l-kawża: l-amministratur tal-uffiċċju jiktbilna fuq contact@vigilae.org biex l-API terġa' tiddaħħal fl-abbonament, u l-istess ċavetta terġa' tiġi aċċettata hekk kif isir dan, sal-iskadenza tagħha stess.

Ċavetta skaduta

Kull ċavetta tiskadi sena wara l-ħolqien — id-data expire_le hija viżibbli fil-console tal-uffiċċju mill-ewwel jum. Il-401 tal-iskadenza huwa espliċitu: jgħid li ċ-ċavetta kienet teżisti u m'għadhiex valida.

Ċavetta API tista' wkoll tieqaf tiġi aċċettata qabel din id-data, meta l-API m'għadhiex parti mill-abbonament tal-uffiċċju. Il-waqfien imbagħad jasal mill-inqas 30 jum wara l-ewwel email, fid-data mogħtija mit-tieni email, mibgħuta mill-inqas 7 ijiem qabel; it-tnejn jintbagħtu lill-amministraturi tal-uffiċċju jew, fin-nuqqas tagħhom, lill-indirizz tal-fatturazzjoni tal-uffiċċju. Hekk kif tiġi ffissata, din id-data tidher fil-console tal-uffiċċju (il-qasam coupure_le ta' GET /connect/cles), u kull tweġiba għal sejħa aċċettata tħabbarha fil-header Sunset sakemm tasal. Wara din id-data, is-sejħa tirċievi l-401 deskritt taħt #authentification, b'"motif": "fin_option_api"; jekk l-API terġa' tiddaħħal fl-abbonament, iċ-ċavetta terġa' tiġi aċċettata, sal-iskadenza tagħha stess.

Ir-rimedju. Oħloq ċavetta ġdida, aqleb is-sejħiet tiegħek fuqha, irrevoka l-qadima. Għal ċavetta API, l-API trid tkun għadha parti mill-abbonament tal-uffiċċju: mingħajrha, il-console tirrifjuta li toħloq waħda. Ippjana din is-sostituzzjoni fl-operazzjonijiet tiegħek minflok ma tiskopriha.

Skop insuffiċjenti

Iċ-ċwievet iġorru l-iskopijiet immarkati meta nħolqu: dawk ġenerali lecture (qari, l-issettjar awtomatiku) u ecriture (kitba), jew dawk fini skont ir-riżorsa (clients:lecture, pieces:ecriture, origine-fonds:lecture, journal:lecture…).

Il-wirt isegwi s-suffiss, f'direzzjoni waħda biss: lecture ikopri kull *:lecture, u ecriture kull *:ecriture — qatt bil-maqlub; skop fini jiftaħ lilu nnifsu biss.

Sitt skopijiet joħorġu minn din il-koppja u ma jintirtu minn ebda ċavetta ġenerali: alertes:qualifier, embed:emettre, adversemedia:consulter, conformite:consulter, dispositif:consulter, integrite:consulter. Il-kwalifikazzjoni ta' avveniment, il-ħruġ ta' token ta' embed, il-qari tal-istampa sfavorevoli ta' fajl jew ta' punteġġ taż-żamma tal-fajl qatt ma joħorġu minn dritt ġenerali ta' qari: kull wieħed jiġi mmarkat għalih.

Ir-rimedju. Oħloq ċavetta li ġġorr l-iskop meħtieġ — u dak biss. L-inqas privileġġ huwa apposta: integrazzjoni li taqra biss m'għandha l-ebda raġuni żżomm ċavetta tal-kitba, u ċavetta wiesgħa qatt mhi se tpatti għal skop li ma ġiex iddelegat espliċitament.

Ma nstabx — jew ta' uffiċċju ieħor

404 ifisser li r-riżorsa ma teżistix jew li hija ta' uffiċċju ieħor. L-API qatt ma tiddistingwi ż-żewġ każijiet: li tiddistingwi jfisser tikxef x'jeżisti band'oħra. Is-separazzjoni hija infurzata fil-livell tad-database, mhux biss fil-kodiċi tal-applikazzjoni.

Ir-rimedju. Iċċekkja s-seq mal-ġurnal tal-uffiċċju li tiegħu hija ċ-ċavetta (GET /api/v1/evenements). Jekk tintegra diversi uffiċċji, kull uffiċċju għandu ċ-ċwievet tiegħu: seq ma jivvjaġġax bejn l-uffiċċji.

Dan il-kont diġà jeżisti

POST /scim/v2/Users fuq userName diġà pprovdut għal dan l-uffiċċju jwieġeb 409 b'scimType: uniqueness. L-uniċità tinżamm minn restrizzjoni tad-database, mhux minn cache: żewġ talbiet ta' ħolqien simultanji ma jistgħux jipproduċu żewġ kontijiet.

Ir-rimedju. Ittratta l-409 bħala suċċess idempotenti, mhux bħala żball: aqra l-kont mill-ġdid b'?filter=userName eq "…" u kompli bl-identifikatur mogħti. Konnettur li jerġa' jipprova f'ċiklu wara 409 qatt mhu se joħloq xejn iżjed.

Dan il-kont jinsab lil hinn mill-ilħiq tad-direttorju

Direttorju la jista' jbaxxi u lanqas jiddiżattiva kont li jġorr setgħat ta' amministrazzjoni tal-uffiċċju: it-talba tiġi miċħuda b'scimType: mutability u rreġistrata. Mingħajr dan il-limitu, konnettur li jadotta l-indirizz tal-uffiċjal tal-konformità jagħlaq l-uffiċċju proprju għal min iwieġeb għalih.

Ir-rimedju. Neħħi lil dik il-persuna mill-ambitu sinkronizzat, jew ibdel ir-rwol tagħha minn ġewwa Vigilae. Iċ-ċaħda tolqot dan il-kont biss: il-bqija tal-lott jiġi applikat normalment.

Rata maqbuża

60 talba fil-minuta għal kull ċavetta, b'mod awtomatiku (tista' tinbidel għal kull ċavetta). It-tweġiba ġġorr Retry-After u l-headers X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.

Ir-rimedju. Irrispetta Retry-After — l-ebda tentattiv mill-ġdid immedjat. Li tolqot il-limitu waqt il-polling huwa kważi dejjem is-sinjal ta' skan mill-ġdid sħiħ: il-kursur depuisSeq qatt ma jerġa' jaqra dak li nqara diġà.

Il-firma ma tiġix ivverifikata min-naħa tiegħek

Ir-riċevitur tiegħek irid jerġa' jikkalkula v1 = HMAC-SHA256(secret, t + "." + body) mill-body mhux ipproċessat (raw) li rċieva, u jirrifjuta kull t eqdem minn 5 min. Il-fallimenti klassiċi: il-body serjalizzat mill-ġdid qabel il-verifika (JSON ifformattjat mill-ġdid m'għadx għandu l-istess bytes), arloġġ li jiżloq lil hinn mit-tolleranza, u rotazzjoni injorata — għal 24 h il-header iġorr v1 waħda għal kull sigriet għadu validu, u trid taċċetta jekk taqbel kwalunkwe waħda.

Ir-rimedju. Ivverifika mal-bytes mhux ipproċessati, issinkronizza l-arloġġ (NTP), ittestja l-verifika tiegħek waqt rotazzjoni. Is-snippets Node u Python fid-dokumentazzjoni jagħmlu eżattament dan — ikkupjahom minflok terġa' tiktibhom.

Avveniment jasal darbtejn

Il-kunsinna hija at-least-once, f'lottijiet ta' mhux aktar minn 100, fl-ordni tal-ġurnal; il-kursur jimxi 'l quddiem biss mat-2xx tiegħek, lott b'lott. Falliment wara r-riċezzjoni iżda qabel ma jimxi l-kursur jikkawża kunsinna mill-ġdid — dak huwa l-kuntratt, mhux difett.

Ir-rimedju. Is-seq hija ċ-ċavetta tal-idempotenza tiegħek: ipproċessa kull sekwenza eżattament darba, u wieġeb 2xx biss wara li tippersisti. 2xx kmieni segwit minn crash huwa l-uniku mod kif jintilef avveniment.

Il-ġurnal jidher mhux komplut jew jirrepeti ruħu

depuisSeq huwa strettament esklussiv: jiġu rritornati biss l-avvenimenti b'seq ogħla, ordnati tielgħin, mhux aktar minn 500 f'paġna. It-tweġiba tirritorna prochainSeq, x'terġa' tgħaddi kif inhu. Paġna iqsar minn limite tfisser tmiem il-ġurnal.

Ir-rimedju. Ippersisti prochainSeq bejn l-eżekuzzjonijiet u qatt terġa' tikkalkulah int. Duplikati jfissru li rġajt tlaqt minn kursur qadim wisq; lakuni jfissru li qbiżt paġna li falliet mingħajr ma erġajt għamiltha.

Parametru barra mill-iskema

Status mhux magħruf, dispożizzjoni barra mil-lista (planifie, traite, ecarte), limite mhux numru sħiħ: it-tweġiba ssemmi l-qasam ħati, u xejn aktar — il-messaġġi ta' żball qatt ma jġorru kontenut tal-fajls.

Ir-rimedju. L-ispeċifikazzjoni OpenAPI hija s-sors: l-enumerazzjonijiet u l-limiti li tiddikjara huma dawk li s-server jinforza, peress li hija servuta minnu stess.

Qasam li l-valur tiegħu huwa twil wisq: Nazzjonalità

It-tweġiba ssemmi l-qasam ħati, u xejn aktar — il-messaġġi ta' żball qatt ma jġorru kontenut tal-fajls.

Ir-rimedju. L-ispeċifikazzjoni OpenAPI hija s-sors: l-enumerazzjonijiet u l-limiti li tiddikjara huma dawk li s-server jinforza, peress li hija servuta minnu stess.

Skop insuffiċjenti (API tar-riżorsi)

L-endpoints tar-riżorsi (/clients, /dossiers, dokumenti, skrinjar, twissijiet) jeħtieġu skop fin: clients:*, dossiers:*, pieces:*, criblage:* jew l-iskop iddedikat alertes:qualifier. Ċavetta legacy lecture tagħti kull skop *:lecture u ecriture kull *:ecriture — iżda alertes:qualifier qatt ma jintiret: il-kwalifikazzjoni ta' twissija hija att tar-responsabbli tal-konformità, iddelegat billi timmarka dak l-iskop mal-ħolqien taċ-ċavetta.

Ir-rimedju. Oħloq ċavetta li ġġorr eżattament l-iskopijiet li teħtieġ l-integrazzjoni tiegħek — u dawk biss. Id-detail tat-tweġiba jsemmi l-iskop nieqes.

Riżorsa ma nstabitx — jew ta' uffiċċju ieħor

L-istess regola bħal #cloisonnement, applikata għar-riżorsi: klijent, fajl, dokument jew twissija li ma jeżistux jew li huma ta' uffiċċju ieħor jirċievu l-istess 404. L-API qatt ma tiddistingwi ż-żewġ każijiet.

Ir-rimedju. Iċċekkja l-identifikatur mal-listi tal-uffiċċju li tiegħu hija ċ-ċavetta. Identifikatur qatt ma jivvjaġġa minn uffiċċju għal ieħor.

Header Idempotency-Key nieqes

Kull POST ta' ħolqien jew ta' skattar (klijent, fajl, dokument, skrinjar, sidien benefiċjarji) jeħtieġ il-header Idempotency-Key: sensiela stabbli ta' mhux aktar minn 200 karattru, waħda għal kull operazzjoni. Meta l-istess ċavetta terġa' tintbagħat bl-istess body, tirritorna l-istess tweġiba, mingħajr effett — il-protezzjoni tiegħek kontra d-duplikati f'inċident tan-netwerk.

Ir-rimedju. Iġġenera ċ-ċavetta qabel l-ewwel tentattiv (UUID wieħed għal kull operazzjoni tan-negozju) u erġa' użaha mhux mibdula għal kull tentattiv mill-ġdid ta' dik l-istess operazzjoni.

Ċavetta tal-idempotenza użata mill-ġdid b'body differenti

Din l-Idempotency-Key diġà ntużat għal body differenti fl-aħħar 24 siegħa. Iċ-ċavetta terġa' tirriproduċi tweġiba, qatt ma tissostitwixxiha: l-użu mill-ġdid tagħha għal operazzjoni ġdida huwa kważi dejjem is-sinjal ta' ċavetta derivata minn kontatur jew minn data mqassra.

Ir-rimedju. Ċavetta ġdida għal kull operazzjoni ġdida. Qatt tidderiva ċ-ċavetta minn data li tirrepeti ruħha bejn l-operazzjonijiet.

Tentattiv oħor bl-istess ċavetta għadu għaddej

Żewġ talbiet bl-istess Idempotency-Key waslu flimkien: l-ewwel waħda tiġi eżegwita, it-tieni tiġi rifjutata qabel kull effett. Huwa dan ir-rifjut li jipprevjeni d-duplikat. Il-każ komuni: proxy jirritorna 502 jew 504 waqt li s-server għadu jaħdem, u l-klijent tiegħek jerġa' jibgħat it-talba. Il-header Retry-After jgħid wara kemm sekondi terġa' tibgħatha.

Ir-rimedju. Erġa' ibgħat l-istess talba, kif inhi, bl-istess ċavetta, wara l-istennija mħabbra: tirċievi t-tweġiba tal-ewwel tentattiv. Qatt ma toħloq ċavetta ġdida biex "tiżblokka" — dan joħloq sewwasew id-duplikat li ċ-ċavetta tevita.

Ambjent tat-test: il-kwota ntlaħqet

Ambjent tat-test għandu limiti fissi: 200 skeda ta' klijent, 50 fajl u 40 dokument għal kull fajl. Ħolqien jew tlugħ ta' dokument li kieku jaqbeż wieħed minnhom jiġi rifjutat qabel kull kitba, u r-rifjut jgħid liema: l-oqsma ressource, quota u courant jġorru r-riżorsa, il-limitu massimu u l-għadd fil-mument tar-rifjut. Meta żewġ talbiet ta' ħolqien simultanji jikkompetu għall-aħħar post, waħda biss tgħaddi. L-editjar ta' skeda jew fajl eżistenti ma jikkonsma xejn.

Ir-rimedju. Dawn il-kwoti mhumiex negozjabbli, u jekk terġa' tibgħat it-talba tirċievi l-istess rifjut. Irrisettja l-ambjent tat-test mill-ispazju tiegħek — jerġa' jibda mid-data ta' dimostrazzjoni — jew ħu abbonament: dawn il-kwoti japplikaw biss għall-ambjenti tat-test.

Fajl issiġillat: ir-reġistru huwa ffriżat

Is-siġillar jiffriża l-katina tal-integrità tal-fajl — dak huwa l-valur probatorju tiegħu. Fajl issiġillat ma jistax jiġi editjat aktar, ma jirċevix aktar dokumenti u ma jerġax jiġi skrinjat minn dan il-kanal. Tibqa' possibbli biss il-kwalifikazzjoni tat-twissijiet: tinkiteb off-chain, ir-ras issiġillata qatt ma tiċċaqlaq.

Ir-rimedju. Xejn x'"tikkoreġi": din hija immutabbiltà apposta. Jekk id-data trid tinbidel, dik hija operazzjoni ġdida ta' diliġenza fl-applikazzjoni, mhux mutazzjoni tal-fajl issiġillat.

Fajl magħluq: ir-relazzjoni kummerċjali ntemmet

Ir-relazzjoni ngħalqet fl-applikazzjoni: il-fajl ma jirċevix aktar kitbiet permezz tal-API — la editjar, la dokument, la skrinjar, u lanqas sidien benefiċjarji. Il-qari jibqa' miftuħ: fajl magħluq jista' jiġi kkonsultat u esportat għat-tul kollu taż-żamma.

Ir-rimedju. Li terġa' tiftaħ ir-relazzjoni huwa att uman u rreġistrat fl-applikazzjoni; l-API ma jagħmlux f'postok. Jekk l-operazzjoni hija ġdida, iftaħ fajl ġdid minflok terġa' tqajjem il-qadim.

Fajl imħassar: id-data tneħħiet

L-iskadenza taż-żamma għaddiet u d-data tal-fajl tħassret. Jibqa' biss it-traċċa tal-awditjar, li tixhed li kien jeżisti fajl u li tħassar fid-data indikata; ma tirċevix aktar ebda kitba.

Ir-rimedju. Xejn x'tikkoreġi u xejn x'terġa' tibgħat: it-tħassir huwa definittiv u maħsub. Identifikatur ta' fajl imħassar miżmum fis-sistemi tiegħek huwa storja, qatt mira ta' kitba.

Format tad-dokument mhux aċċettat

Id-dokumenti ta' sostenn jaċċettaw PDF, JPG, JPEG, PNG u WEBP — l-istess formati bħall-applikazzjoni. Il-kontroll isir fuq l-estensjoni tal-filename obbligatorju: dokument mingħajr isem ta' fajl validu jiġi rifjutat, ikun xi jkun il-kontenut tiegħu.

Ir-rimedju. Ikkonverti qabel ma tibgħat (scan TIFF jew HEIC jiġi kkonvertit f'PDF jew JPEG) u ibgħat il-kontenut bħala base64 standard f'contenu, b'type minn fost il-kodiċijiet stabbli a_doc_*.

Dokument akbar minn 6 MB

Il-limitu japplika għall-fajl iddekodifikat (6 MB), l-istess bħal fl-applikazzjoni u fil-portal tal-ġbir. Peress li base64 iżid terz ta' piż ta' kodifikazzjoni, il-body tat-talba jaċċetta sa 9 MB.

Ir-rimedju. Ikkomprimi d-dokument (PDF skannjat bil-kulur f'300 dpi kważi dejjem jinżel taħt il-limitu bil-griż) minflok ma taqsmu.

Sors tal-iskrinjar mhux disponibbli

L-ebda waħda mill-entitajiet tal-fajl ma setgħet tiġi vverifikata mal-listi: is-sors (l-indiċi tal-listi uffiċjali jew il-fornitur) ma weġibx. L-API tirrifjuta li tikkonkludi — rapport "nadif" fuq sors mejjet ikun l-agħar negattiv falz possibbli. Il-falliment jiġi rreġistrat fuq il-fajl (erreurSource). Interruzzjoni parzjali ma tipproduċix dan il-502: it-tweġiba 200 iżżomm il-qbil tal-entitajiet li wieġbu u ssemmi dawk li fallew f'erreurSourceEntites.

Ir-rimedju. Erġa' agħmel l-istess sejħa aktar tard, bl-istess Idempotency-Key: l-idempotenza tiftakar biss it-tweġibiet ta' suċċess — meta terġa' tipprova wara żball, isir skrinjar reali.

Widgets inkorporati mhux attivati fuq din l-istanza

Il-mint POST /api/v1/embed/jetons jiddependi mill-oriġini ddikjarati tal-uffiċċju tiegħek — il-lista hija dik li tmexxi l-CSP frame-ancestors tax-shell inkorporat. Dan il-501 jgħid li l-istanza li sejjaħt ma ġġorrx dak il-ħażna: is-superfiċje tal-embed hemmhekk hija inerti bil-kostruzzjoni, u tgħid dan minflok toħroġ token li l-ebda oriġini ma tkun tista' turi. Ma għandux jiġi konfuż mal-400 mogħti lil uffiċċju li l-oriġini tiegħu għadhom ma ġewx iddikjarati.

Ir-rimedju. Dan il-501 jitkellem dwar l-istanza, mhux dwar it-talba tiegħek. Fuq vigilae.org, l-amministratur tal-uffiċċju tiegħek jiddikjara l-oriġini hu stess, fuq l-iskrin "Integrazzjonijiet u sigurtà" (il-kaxxa fit-taqsima tal-widgets tgħid fejn); imbagħad erġa' agħmel l-istess sejħa. Xejn x'tibdel fil-kodiċi tiegħek: it-talba kienet tajba, l-istanza ma kinitx lesta.

Superfiċi mhux disponibbli f'din l-installazzjoni

Żewġ qari bażiċi — GET /api/v1/dossiers/{id}/origine-fonds u GET /api/v1/dossiers/{id}/exigences — jistrieħu fuq ħażniet li mhux kull istanza ġġorr. Meta waħda tkun nieqsa, l-API jgħidha minflok ma jservi lista vojta: “xejn x'jiġi rrappurtat” u “xejn ma nqara” huma fatti opposti, u li tħawwadhom iġġib fajl li ħadd ma ħares lejh bħal fajl mingħajr riżervi. Dan il-501 jitkellem dwar l-istanza msejħa, qatt dwar it-talba tiegħek u lanqas dwar il-fajl.

Ir-rimedju. Terġax issejjaħ f'ċiklu: xejn mhu se jinbidel sakemm l-istanza ma ġġorrx dik il-ħażna. Ittratta dan il-kodiċi bħala “data mhux disponibbli hawn” u fuq kollox tgħoddux bħala żero fid-dashboards tiegħek — hekk kejl nieqes isir ċifra ħażina. Fuq vigilae.org iż-żewġ qari huma servuti; f'installazzjoni ddedikata, l-aġġornament tal-ħażna huwa f'idejn l-operatur tiegħek.