Iga viga, selgitatud püsival aadressil.

Võti puudub, on vigane või tundmatu

API autendib eranditult päise Authorization: Bearer vgk_… kaudu — mitte kunagi seansiküpsise kaudu. Tühistatud võti muutub tundmatuks tühistamise hetkel.

Sama 401 vastuses on "motif": "fin_option_api", kui võtme kehtivus on lõpetatud, sest API ei kuulu enam büroo tellimusse. Selle lõpetamise kuupäev on nimetatud e-kirjas büroo administraatoritele või nende puudumisel büroo arveldusaadressile ja seejärel teatatud iga vastu võetud päringu vastuse päises Sunset (ajakava: #cle-expiree). Põhjuseta võib see tulla ka peatatud tellimusest: peatamine katkestab võtmed kohe.

Parandus. Kontrollige, et päis tegelikult teele läheb (puhverserverid vahel eemaldavad selle), et võti algab vgk_-ga ja et seda ei ole büroo konsoolist tühistatud. Kuna saladust kuvatakse ainult loomisel, siis kadunud võti asendatakse, mitte ei taastata. Kui vastuses on "motif": "fin_option_api", ei ole viga päises ega võtmes: büroo administraator kirjutab meile aadressil contact@vigilae.org, et API taas tellimusse lisataks, ja sama võti kehtib uuesti kohe, kui see on tehtud, kuni oma kehtivusaja lõpuni.

Aegunud võti

Iga võti aegub aasta pärast loomist — kuupäev expire_le on büroo konsoolis nähtav esimesest päevast peale. Aegumise 401 on selgesõnaline: see ütleb, et võti oli olemas ega kehti enam.

API-võtme kehtivus võib lõppeda ka enne seda kuupäeva, kui API ei kuulu enam büroo tellimusse. Lõpp saabub siis vähemalt 30 päeva pärast esimest e-kirja, kuupäeval, mille nimetab teine e-kiri, mis saadetakse vähemalt 7 päeva ette; mõlemad saadetakse büroo administraatoritele või nende puudumisel büroo arveldusaadressile. Kui see kuupäev on määratud, on see nähtav büroo konsoolis (GET /connect/cles väli coupure_le) ja iga vastu võetud päringu vastus teatab sellest päises Sunset, kuni see kätte jõuab. Pärast seda kuupäeva saab päring #authentification all kirjeldatud 401, väljaga "motif": "fin_option_api"; kui API kuulub taas tellimusse, kehtib võti uuesti, kuni oma kehtivusaja lõpuni.

Parandus. Looge uus võti, suunake oma päringud sellele ümber, tühistage vana. API-võtme puhul peab API kuuluma endiselt büroo tellimusse: ilma selleta keeldub konsool võtit loomast. Kavandage see asendus oma töökorraldusse, selle asemel et seda avastada.

Ebapiisav skoop

Võtmed kannavad loomisel märgitud skoope: üldised lecture (lugemine, vaikimisi) ja ecriture (kirjutamine) või peeneteralised ressursi kaupa (clients:lecture, pieces:ecriture, origine-fonds:lecture, journal:lecture…).

Pärimine käib järelliite järgi, ainult ühes suunas: lecture katab iga *:lecture, ecriture iga *:ecriture — vastupidi mitte kunagi; peeneteraline skoop avab ainult iseenda.

Kuus skoopi jäävad sellest paarist välja ega päri ühestki üldisest võtmest: alertes:qualifier, embed:emettre, adversemedia:consulter, conformite:consulter, dispositif:consulter, integrite:consulter. Sündmuse kvalifitseerimine, manustamisloa väljastamine, toimiku ebasoodsa meediakajastuse või toimiku hoolsushinde lugemine ei tulene kunagi üldisest lugemisõigusest: iga skoop märgitakse eraldi.

Parandus. Looge võti, mis kannab vajalikku skoopi — ja ainult seda. Vähim õigus on taotluslik: liidestusel, mis ainult loeb, ei ole põhjust hoida kirjutamisvõtit, ja lai võti ei asenda kunagi skoopi, mida pole sõnaselgelt delegeeritud.

Ei leitud — või kuulub teisele büroole

404 tähendab, et ressurssi ei ole olemas või see kuulub teisele büroole. API ei erista neid kaht juhtu kunagi: eristamine paljastaks, mis mujal olemas on. Eraldatus jõustatakse andmebaasi tasandil, mitte ainult rakenduskoodis.

Parandus. Kontrollige seq-i selle büroo päeviku vastu, kellele võti kuulub (GET /api/v1/evenements). Kui liidestate mitut bürood, on igal bürool oma võtmed: seq ei rända büroode vahel.

See konto on juba olemas

POST /scim/v2/Users sellele büroole juba loodud userName-i peale vastab 409 ja scimType: uniqueness. Ainulisust hoiab andmebaasi piirang, mitte vahemälu: kaks samaaegset loomist ei saa anda kahte kontot.

Parandus. Käsitlege 409 kui idempotentset õnnestumist, mitte kui viga: lugege konto tagasi päringuga ?filter=userName eq "…" ja jätkake tagastatud identifikaatoriga. Konnektor, mis 409 järel silmuses uuesti proovib, ei loo kunagi midagi enamat.

See konto on kataloogi haardest väljas

Kataloog ei saa büroo haldusvolitusi kandvat kontot alandada ega deaktiveerida: päring lükatakse tagasi koodiga scimType: mutability ja logitakse. Ilma selle piirita sulgeks vastavusametniku aadressi üle võttev konnektor büroo just selle ees, kes selle eest vastutab.

Parandus. Eemaldage see isik sünkroonitavast ulatusest või muutke tema roll Vigilaes. Keeldumine puudutab ainult seda kontot: partii ülejäänud osa rakendatakse tavapäraselt.

Päringumäär ületatud

60 päringut minutis võtme kohta, vaikimisi (võtmekaupa muudetav). Vastus kannab päist Retry-After ning päiseid X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.

Parandus. Austage päist Retry-After — mitte mingit kohest uuesti proovimist. Piirini jõudmine pollimise ajal on peaaegu alati täieliku uuesti läbikäimise märk: kursor depuisSeq ei loe kunagi uuesti seda, mis on juba loetud.

Allkiri ei klapi teie poolel

Teie vastuvõtja peab arvutama v1 = HMAC-SHA256(secret, t + "." + body) uuesti saadud toorest kehast ja lükkama tagasi iga t, mis on vanem kui 5 min. Klassikalised läbikukkumised: enne kontrolli uuesti serialiseeritud keha (ümbervormindatud JSON-il ei ole enam samad baidid), tolerantsist välja triiviv kell ja tähelepanuta jäetud rotatsioon — 24 t jooksul kannab päis üht v1 iga veel kehtiva saladuse kohta ja te peate aktsepteerima, kui mõni neist klapib.

Parandus. Kontrollige toorbaitide vastu, sünkroonige oma kell (NTP), testige oma kontrolli rotatsiooni ajal. Node'i ja Pythoni näidised dokumentatsioonis teevad täpselt seda — kopeerige need, selle asemel et neid ümber kirjutada.

Sündmus saabub kaks korda

Kohaletoimetamine on at-least-once, kuni 100 kaupa partiides, päeviku järjekorras; kursor liigub edasi ainult teie 2xx peale, partii kaupa. Tõrge pärast vastuvõttu, kuid enne kursori edasiliikumist, toob kaasa uuesti saatmise — see on leping, mitte defekt.

Parandus. seq on teie idempotentsusvõti: töödelge iga järjenumber täpselt üks kord ja vastake 2xx alles pärast püsisalvestust. Liiga varane 2xx, millele järgneb krahh, on ainus viis sündmust kaotada.

Päevik näib poolik või kordab end

depuisSeq on rangelt välistav: tagastatakse ainult suurema seq-ga sündmused, kasvavalt sorditud, kuni 500 lehekülje kohta. Vastus tagastab prochainSeq, mis tuleb muutmata kujul tagasi anda. Lehekülg, mis on lühem kui limite, tähendab päeviku lõppu.

Parandus. Säilitage prochainSeq käivituste vahel püsivalt ja ärge arvutage seda kunagi ise. Duplikaadid tähendavad, et alustasite liiga vanast kursorist; augud tähendavad, et jätsite ebaõnnestunud lehekülje vahele seda kordamata.

Parameeter väljaspool skeemi

Tundmatu staatus, otsustus väljaspool loendit (planifie, traite, ecarte), mittetäisarvuline limite: vastus nimetab vigase välja ja ei midagi muud — veateated ei kanna kunagi toimiku sisu.

Parandus. OpenAPI spetsifikatsioon on allikas: selle deklareeritud loetelud ja piirid on needsamad, mida server jõustab, sest server ise seda serveerib.

Väli, mille väärtus on liiga pikk: Kodakondsus

Vastus nimetab vigase välja ja ei midagi muud — veateated ei kanna kunagi toimiku sisu.

Parandus. OpenAPI spetsifikatsioon on allikas: selle deklareeritud loetelud ja piirid on needsamad, mida server jõustab, sest server ise seda serveerib.

Ebapiisav skoop (ressursi-API)

Ressursi otspunktid (/clients, /dossiers, dokumendid, sõelumine, hoiatused) nõuavad peenteralist skoopi: clients:*, dossiers:*, pieces:*, criblage:* või sihtotstarbeline skoop alertes:qualifier. Pärandvõti skoobiga lecture annab kõik *:lecture skoobid ja ecriture kõik *:ecriture omad — kuid alertes:qualifier ei pärandu kunagi: hoiatuse kvalifitseerimine on vastutava isiku tegu, mis delegeeritakse selle skoobi märkimisega võtme loomisel.

Parandus. Looge võti, mis kannab täpselt neid skoope, mida teie liidestus vajab — ja ainult neid. Vastuse väli detail nimetab puuduva skoobi.

Ressurssi ei leitud — või kuulub teisele büroole

Sama reegel nagu #cloisonnement, rakendatud ressurssidele: klient, toimik, dokument või hoiatus, mida ei ole olemas või mis kuulub teisele büroole, saab sama 404. API ei erista neid kaht juhtu kunagi.

Parandus. Kontrollige identifikaatorit selle büroo loendite vastu, kellele võti kuulub. Identifikaator ei rända kunagi ühest büroost teise.

Päis Idempotency-Key puudub

Iga loov või käivitav POST (klient, toimik, dokument, sõelumine, tegelikud kasusaajad) nõuab päist Idempotency-Key: stabiilne kuni 200 tähemärgi pikkune string, üks operatsiooni kohta. Sama võtme kordamine sama kehaga tagastab sama vastuse, ilma mõjuta — teie kaitse duplikaatide vastu võrguintsidendi korral.

Parandus. Genereerige võti enne esimest katset (üks UUID ärioperatsiooni kohta) ja taaskasutage seda muutmata kujul sellesama operatsiooni igal kordamisel.

Idempotentsusvõti taaskasutatud teistsuguse kehaga

Seda Idempotency-Key-d on viimase 24 tunni jooksul juba kasutatud teistsuguse kehaga. Võti kordab vastust, mitte kunagi ei kirjuta seda üle: selle taaskasutamine uue operatsiooni jaoks on peaaegu alati märk võtmest, mis on tuletatud loendurist või kärbitud kuupäevast.

Parandus. Iga uue operatsiooni jaoks uus võti. Ärge tuletage võtit kunagi andmetest, mis operatsioonide vahel korduvad.

Teine katse sama võtmega on veel pooleli

Kaks päringut sama Idempotency-Key-ga saabusid koos: esimene täidetakse, teine lükatakse tagasi enne igasugust mõju. Just see tagasilükkamine hoiab ära duplikaadi. Tavaline juhtum: proksi vastab 502 või 504, kui server veel töötab, ja teie klient kordab päringut. Päis Retry-After ütleb, mitme sekundi pärast seda korrata.

Parandus. Korrake sama päringut muutmata kujul, sama võtmega, pärast teatatud ooteaega: saate esimese katse vastuse. Ärge kunagi looge uut võtit, et „vabastada“ — see looks just selle duplikaadi, mida võti väldib.

Testkeskkond: kvoot on täis

Testkeskkonnal on kindlad piirid: 200 kliendikaarti, 50 toimikut ja 40 dokumenti toimiku kohta. Loomine või üleslaadimine, mis ületaks neist ühe, lükatakse tagasi enne igasugust kirjutamist ja tagasilükkamine ütleb, milline neist: väljad ressource, quota ja courant näitavad ressurssi, ülempiiri ja seisu tagasilükkamise hetkel. Kui kaks samaaegset loomist võistlevad viimase koha pärast, pääseb läbi ainult üks. Olemasoleva kliendikaardi või toimiku muutmine kvooti ei kuluta.

Parandus. Need kvoodid ei ole läbiräägitavad ja päringu kordamine toob sama tagasilükkamise. Lähtestage testkeskkond oma kontolt — see algab uuesti näidisandmetest — või vormistage tellimus: need kvoodid kehtivad ainult testkeskkondadele.

Pitseeritud toimik: register on külmutatud

Pitseerimine külmutab toimiku terviklusahela — selles seisnebki selle tõenduslik väärtus. Pitseeritud toimikut ei saa enam muuta, see ei võta enam vastu dokumente ja seda ei kordussõeluta enam selle kanali kaudu. Võimalikuks jääb ainult hoiatuse kvalifitseerimine: see kirjutatakse ahelaväliselt, pitseeritud pea ei liigu kunagi.

Parandus. „Parandada“ ei ole siin midagi: see on taotluslik muutumatus. Kui andmed peavad muutuma, on see uus hoolsusoperatsioon rakenduses, mitte pitseeritud toimiku muteerimine.

Suletud toimik: ärisuhe on lõppenud

Suhe lõpetati rakenduses: toimik ei võta API kaudu enam kirjeid vastu — ei muudatust, ei dokumenti, ei sõelumist ega tegelikke kasusaajaid. Lugemine jääb avatuks: suletud toimikut saab kogu säilitusaja jooksul vaadata ja eksportida.

Parandus. Suhte uuesti avamine on inimese tehtud ja logitud toiming rakenduses; API ei tee seda teie eest. Kui operatsioon on uus, avage uus toimik, mitte elustage vana.

Kustutatud toimik: andmed on eemaldatud

Säilitustähtaeg on möödunud ja toimiku andmed on kustutatud. Alles jääb üksnes auditijälg, mis tõendab, et toimik oli olemas ja et see nimetatud kuupäeval kustutati; see ei võta enam ühtegi kirjet vastu.

Parandus. Midagi ei ole parandada ega korrata: kustutamine on lõplik ja taotluslik. Teie süsteemides hoitud kustutatud toimiku tunnus on ajalugu, mitte kunagi kirjutamise sihtmärk.

Dokumendi vorming ei ole vastuvõetav

Tõendusdokumentidel aktsepteeritakse vorminguid PDF, JPG, JPEG, PNG ja WEBP — samu vorminguid mis rakenduses. Kontroll käib kohustusliku filename-i laiendi järgi: ilma kehtiva failinimeta dokument lükatakse tagasi, olgu selle sisu milline tahes.

Parandus. Teisendage enne saatmist (TIFF- või HEIC-skann teiseneb PDF-iks või JPEG-iks) ja saatke sisu standardse base64-na väljas contenu, koos type-iga stabiilsete a_doc_* koodide seast.

Dokument üle 6 MB

Piirang kehtib dekodeeritud failile (6 MB), sama mis rakenduses ja kogumisportaalis. Kuna base64 lisab kolmandiku jagu kodeerimiskulu, aktsepteerib päringu keha kuni 9 MB.

Parandus. Tihendage dokumenti (värviline 300 dpi skannitud PDF langeb halltoonides peaaegu alati alla piiri), selle asemel et seda tükeldada.

Sõelumisallikas ei ole kättesaadav

Ühtegi toimiku üksust ei õnnestunud loendite vastu kontrollida: allikas (ametlike loendite indeks või teenusepakkuja) ei vastanud. API keeldub järeldust tegemast — „puhas“ raport surnud allika peal oleks halvim võimalik valenegatiiv. Tõrge talletatakse toimikule (erreurSource). Osaline katkestus seda 502 ei tekita: 200-vastus säilitab vastanud üksuste vasted ja nimetab ebaõnnestunud üksused väljas erreurSourceEntites.

Parandus. Korrake sama päringut hiljem, sama Idempotency-Key-ga: idempotentsus jätab meelde ainult õnnestunud vastused — kordamine pärast viga käivitab tegeliku sõelumise.

Manustatud vidinad ei ole selles instantsis aktiveeritud

Väljastaja POST /api/v1/embed/jetons toetub teie büroo jaoks deklareeritud päritoludele — just see loend juhib manustatud shelli frame-ancestors CSP-d. See 501 ütleb, et instants, mida te kutsusite, ei kanna seda hoidlat: manustamispind on seal ehituslikult inertne ja ütleb seda, selle asemel et väljastada token, mida ükski päritolu kunagi kuvada ei saaks. Mitte segi ajada 400-ga, mis tagastatakse büroole, kelle päritolud ei ole veel deklareeritud.

Parandus. See 501 räägib instantsist, mitte teie päringust. Vigilae.org-is deklareerib teie büroo administraator päritolud ise, ekraanil „Integratsioonid ja turvalisus“ (täpne koht on kirjas vidinate jaotise kastis); seejärel korrake sama päringut. Teie koodis pole midagi muuta: päring oli korras, instants ei olnud valmis.

Pind ei ole selles paigalduses saadaval

Kaks aluslugemist — GET /api/v1/dossiers/{id}/origine-fonds ja GET /api/v1/dossiers/{id}/exigences — tuginevad hoidlatele, mida iga eksemplar ei kanna. Kui üks puudub, ütleb API seda tühja loendi asemel: „pole midagi märkida“ ja „midagi ei loetud“ on vastandlikud faktid ning nende segiajamine muudaks toimiku, mida keegi pole vaadanud, märkusteta toimikuks. See 501 puudutab kutsutud eksemplari, mitte kunagi teie päringut ega toimikut.

Parandus. Ärge korrake päringut tsüklis: midagi ei muutu enne, kui eksemplar seda hoidlat kannab. Käsitlege koodi kui „andmed pole siin saadaval“ ja ennekõike ärge lugege seda oma töölaudadel nulliks — nõnda saab puuduvast mõõtmisest vale arv. Saidil vigilae.org teenindatakse mõlemat lugemist; pühendatud paigalduses on hoidla uuendamine teie käitaja asi.