Jokainen virhe, selitettynä pysyvässä osoitteessa.

Avain puuttuu, on virheellinen tai tuntematon

API todentaa yksinomaan Authorization: Bearer vgk_… -otsakkeella — ei koskaan istuntoevästeellä. Peruttu avain muuttuu tuntemattomaksi perumishetkellä.

Sama 401 sisältää kentän "motif": "fin_option_api", kun avain on pysäytetty, koska API ei enää kuulu toimiston tilaukseen. Pysäytyksen päivämäärä ilmoitettiin toimiston ylläpitäjille tai, jos heitä ei ole, toimiston laskutusosoitteeseen lähetetyssä sähköpostissa ja sen jälkeen jokaisen hyväksyttyyn kutsuun annetun vastauksen Sunset-otsakkeessa (aikataulu: #cle-expiree). Ilman syykenttää se voi johtua myös keskeytetystä tilauksesta: keskeytys katkaisee avaimet heti.

Korjaava toimenpide. Tarkista, että otsake todella lähtee (välityspalvelimet joskus riisuvat sen), että avain alkaa etuliitteellä vgk_ ja ettei sitä ole peruttu toimiston konsolista. Koska salaisuus näytetään vain luontihetkellä, kadonnut avain korvataan, ei palauteta. Kun vastauksessa on "motif": "fin_option_api", vika ei ole otsakkeessa eikä avaimessa: toimiston ylläpitäjä kirjoittaa meille osoitteeseen contact@vigilae.org, jotta API palautetaan tilaukseen, ja sama avain hyväksytään taas heti, kun se on tehty, oman voimassaolonsa päättymiseen asti.

Vanhentunut avain

Jokainen avain vanhenee vuosi luonnin jälkeen — expire_le-päivämäärä näkyy toimiston konsolissa ensimmäisestä päivästä alkaen. Vanhenemisen 401 on yksiselitteinen: se kertoo, että avain oli olemassa eikä ole enää voimassa.

API-avainta voidaan lakata hyväksymästä myös ennen tätä päivämäärää, kun API ei enää kuulu toimiston tilaukseen. Pysäytys tapahtuu silloin vähintään 30 päivää ensimmäisen sähköpostin jälkeen, päivänä, jonka toinen, vähintään 7 päivää etukäteen lähetetty sähköposti ilmoittaa; molemmat lähetetään toimiston ylläpitäjille tai, jos heitä ei ole, toimiston laskutusosoitteeseen. Kun päivämäärä on asetettu, se näkyy toimiston konsolissa (GET /connect/cles -kenttä coupure_le), ja jokainen hyväksyttyyn kutsuun annettu vastaus ilmoittaa sen Sunset-otsakkeessa, kunnes se koittaa. Sen jälkeen kutsu saa kohdassa #authentification kuvatun 401:n, kentällä "motif": "fin_option_api"; jos API palaa tilaukseen, avain hyväksytään taas, oman voimassaolonsa päättymiseen asti.

Korjaava toimenpide. Luo uusi avain, siirrä kutsusi sille, peru vanha. API-avaimen kohdalla API:n on yhä kuuluttava toimiston tilaukseen: ilman sitä konsoli kieltäytyy luomasta avainta. Suunnittele vaihto osaksi operaatioitasi sen sijaan, että huomaisit sen yllätyksenä.

Riittämätön scope

Avaimet kantavat luonnissa valitut scopet: yleiset lecture (luku, oletus) ja ecriture (kirjoitus) tai hienojakoiset resurssikohtaiset (clients:lecture, pieces:ecriture, origine-fonds:lecture, journal:lecture…).

Periytyminen seuraa päätettä, vain yhteen suuntaan: lecture kattaa jokaisen *:lecture-scopen ja ecriture jokaisen *:ecriture-scopen — toisin päin ei koskaan; hienojakoinen scope avaa vain itsensä.

Kuusi scopea jää tämän parin ulkopuolelle eikä periydy mistään yleisestä avaimesta: alertes:qualifier, embed:emettre, adversemedia:consulter, conformite:consulter, dispositif:consulter, integrite:consulter. Tapahtuman kvalifiointi, upotustunnisteen myöntäminen, asian kielteisen lehdistöaineiston tai asianhoidon arvosanan lukeminen ei seuraa koskaan yleisestä lukuoikeudesta: jokainen valitaan erikseen.

Korjaava toimenpide. Luo avain, joka kantaa tarvittavan scopen — ja vain sen. Vähimpien oikeuksien periaate on tarkoituksellinen: pelkästään lukevalla integraatiolla ei ole mitään syytä pitää kirjoitusavainta, eikä laaja avain koskaan korvaa scopea, jota ei ole nimenomaisesti delegoitu.

Ei löydy — tai kuuluu toiselle toimistolle

404 tarkoittaa, että resurssia ei ole olemassa tai että se kuuluu toiselle toimistolle. API ei koskaan erottele näitä kahta tapausta: erottelu paljastaisi, mitä muualla on. Eristys pakotetaan tietokantatasolla, ei vain sovelluskoodissa.

Korjaava toimenpide. Tarkista seq sen toimiston lokista, jolle avain kuuluu (GET /api/v1/evenements). Jos integroit useita toimistoja, jokaisella on omat avaimensa: seq ei siirry toimistosta toiseen.

Tämä tili on jo olemassa

POST /scim/v2/Users tälle toimistolle jo luodulle userName-tunnukselle vastaa 409 ja scimType: uniqueness. Ainutkertaisuutta pitää yllä tietokantarajoite, ei välimuisti: kaksi samanaikaista luontia ei voi tuottaa kahta tiliä.

Korjaava toimenpide. Käsittele 409 idempotenttina onnistumisena, ei virheenä: lue tili takaisin haulla ?filter=userName eq "…" ja jatka palautetulla tunnisteella. Liitin, joka yrittää 409:n jälkeen silmukassa uudelleen, ei koskaan luo mitään lisää.

Tämä tili on hakemiston ulottumattomissa

Hakemisto ei voi alentaa eikä poistaa käytöstä tiliä, jolla on toimiston hallintavaltuudet: pyyntö hylätään koodilla scimType: mutability ja kirjataan lokiin. Ilman tätä rajaa liitin, joka ottaa vastuuhenkilön osoitteen, sulkisi toimiston juuri siltä, joka siitä vastaa.

Korjaava toimenpide. Jätä tämä henkilö pois synkronoitavasta joukosta tai vaihda hänen roolinsa Vigilaessa. Hylkäys koskee vain tätä tiliä: erän loppuosa käsitellään normaalisti.

Kutsuraja ylitetty

60 pyyntöä minuutissa avainta kohti, oletuksena (yliajettavissa avainkohtaisesti). Vastaus kantaa Retry-After-otsakkeen sekä otsakkeet X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.

Korjaava toimenpide. Kunnioita Retry-After-otsaketta — ei välitöntä uusintayritystä. Rajan osuminen pollatessa on lähes aina merkki täydestä uudelleenluvusta: depuisSeq-kursori ei koskaan lue uudelleen jo luettua.

Allekirjoitus ei todennu sinun puolellasi

Vastaanottimesi on laskettava v1 = HMAC-SHA256(secret, t + "." + body) uudelleen vastaanotetusta raa'asta rungosta ja hylättävä jokainen yli 5 min vanha t. Klassiset kompastuskivet: runko sarjallistettu uudelleen ennen todennusta (uudelleenmuotoiltu JSON ei enää ole tavulleen sama), toleranssin yli ryöminyt kello ja huomiotta jätetty kierrätys — 24 h ajan otsake kantaa yhden v1-arvon kutakin yhä voimassa olevaa salaisuutta kohti, ja sinun on hyväksyttävä, jos yksikin täsmää.

Korjaava toimenpide. Todenna raakoja tavuja vasten, synkronoi kellosi (NTP), testaa todennuksesi kierrätyksen aikana. Dokumentaation Node- ja Python-esimerkit tekevät täsmälleen tämän — kopioi ne sen sijaan, että kirjoittaisit ne uudelleen.

Tapahtuma saapuu kahdesti

Toimitus on at-least-once, enintään 100 tapahtuman erissä, lokin järjestyksessä; kursori etenee vain 2xx-vastauksestasi, erä kerrallaan. Virhe vastaanoton jälkeen mutta ennen kursorin etenemistä aiheuttaa uusintatoimituksen — se on sopimus, ei vika.

Korjaava toimenpide. seq on idempotenssiavaimesi: käsittele jokainen järjestysnumero täsmälleen kerran ja vastaa 2xx vasta talletuksen jälkeen. Ennenaikainen 2xx ja sitä seuraava kaatuminen on ainoa tapa menettää tapahtuma.

Loki näyttää vajaalta tai toistaa itseään

depuisSeq on aidosti poissulkeva: vain suuremman seq-arvon tapahtumat palautetaan, nousevasti lajiteltuina, enintään 500 sivua kohti. Vastaus palauttaa prochainSeq-arvon, joka annetaan takaisin sellaisenaan. limite-arvoa lyhyempi sivu tarkoittaa lokin loppua.

Korjaava toimenpide. Talleta prochainSeq ajokertojen välillä äläkä koskaan laske sitä itse uudelleen. Kaksoiskappaleet tarkoittavat, että aloitit liian vanhasta kursorista; aukot tarkoittavat, että ohitit epäonnistuneen sivun toistamatta sitä.

Parametri skeeman ulkopuolella

Tuntematon tila, listan ulkopuolinen käsittelytapa (planifie, traite, ecarte), ei-kokonaislukuinen limite: vastaus nimeää virheellisen kentän, eikä mitään muuta — virheilmoitukset eivät koskaan kanna aineistojen sisältöä.

Korjaava toimenpide. OpenAPI-määrittely on lähde: sen ilmoittamat luetteloarvot ja rajat ovat samat, jotka palvelin valvoo, koska palvelin itse tarjoilee määrittelyn.

Kentän arvo on liian pitkä: Kansalaisuus

Vastaus nimeää virheellisen kentän, eikä mitään muuta — virheilmoitukset eivät koskaan kanna aineistojen sisältöä.

Korjaava toimenpide. OpenAPI-määrittely on lähde: sen ilmoittamat luetteloarvot ja rajat ovat samat, jotka palvelin valvoo, koska palvelin itse tarjoilee määrittelyn.

Riittämätön scope (resurssi-API)

Resurssipäätepisteet (/clients, /dossiers, asiakirjat, seulonta, hälytykset) vaativat hienojakoisen scopen: clients:*, dossiers:*, pieces:*, criblage:* tai erillisen alertes:qualifier-scopen. Vanha lecture-avain myöntää kaikki *:lecture-scopet ja ecriture kaikki *:ecriture-scopet — mutta alertes:qualifier ei koskaan periydy: hälytyksen kvalifiointi on vastuuhenkilön toimi, joka delegoidaan rastittamalla kyseinen scope avainta luotaessa.

Korjaava toimenpide. Luo avain, joka kantaa täsmälleen integraatiosi tarvitsemat scopet — ja vain ne. Vastauksen detail-kenttä nimeää puuttuvan scopen.

Resurssia ei löydy — tai se kuuluu toiselle toimistolle

Sama sääntö kuin #cloisonnement, sovellettuna resursseihin: asiakas, aineisto, asiakirja tai hälytys, jota ei ole olemassa tai joka kuuluu toiselle toimistolle, saa saman 404-vastauksen. API ei koskaan erottele näitä kahta tapausta.

Korjaava toimenpide. Tarkista tunniste sen toimiston listauksista, jolle avain kuuluu. Tunniste ei koskaan siirry toimistosta toiseen.

Idempotency-Key-otsake puuttuu

Jokainen luova tai käynnistävä POST (asiakas, aineisto, asiakirja, seulonta, tosiasialliset edunsaajat) vaatii Idempotency-Key-otsakkeen: vakaa, enintään 200 merkin merkkijono, yksi operaatiota kohti. Saman avaimen toistaminen samalla rungolla palauttaa saman vastauksen ilman vaikutusta — suojasi kaksoiskappaleita vastaan verkkohäiriössä.

Korjaava toimenpide. Generoi avain ennen ensimmäistä yritystä (yksi UUID liiketoimintaoperaatiota kohti) ja käytä sitä muuttumattomana saman operaation jokaisessa uusintayrityksessä.

Idempotenssiavain käytetty uudelleen eri rungolla

Tämä Idempotency-Key on jo käytetty eri rungolle viimeisten 24 tunnin aikana. Avain toistaa vastauksen, se ei koskaan korvaa sitä: avaimen uusiokäyttö uuteen operaatioon on lähes aina merkki laskurista tai katkaistusta päivämäärästä johdetusta avaimesta.

Korjaava toimenpide. Uusi avain jokaiselle uudelle operaatiolle. Älä koskaan johda avainta tiedoista, jotka toistuvat operaatiosta toiseen.

Toinen yritys samalla avaimella on vielä kesken

Kaksi pyyntöä samalla Idempotency-Key-avaimella saapui yhtä aikaa: ensimmäinen suoritetaan, toinen hylätään ennen mitään vaikutusta. Juuri tämä hylkäys estää kaksoiskappaleen. Tavallinen tapaus: välityspalvelin palauttaa 502 tai 504 palvelimen vielä työskennellessä, ja asiakasohjelmasi toistaa pyynnön. Otsake Retry-After kertoo, kuinka monen sekunnin kuluttua se toistetaan.

Korjaava toimenpide. Toista sama pyyntö sellaisenaan, samalla avaimella, ilmoitetun odotuksen jälkeen: saat ensimmäisen yrityksen vastauksen. Älä koskaan luo uutta avainta ”vapauttaaksesi” — se loisi juuri sen kaksoiskappaleen, jonka avain estää.

Testiympäristö: kiintiö on täynnä

Testiympäristöllä on kiinteät rajat: 200 asiakasta, 50 aineistoa ja 40 asiakirjaa aineistoa kohden. Luonti tai asiakirjan tallennus, joka ylittäisi jonkin niistä, hylätään ennen kuin mitään kirjoitetaan, ja hylkäys kertoo, mistä rajasta on kyse: kentät ressource, quota ja courant sisältävät resurssin, ylärajan ja määrän hylkäyshetkellä. Jos kaksi samanaikaista luontia kilpailee viimeisestä paikasta, vain toinen menee läpi. Olemassa olevan asiakkaan tai aineiston muokkaaminen ei kuluta kiintiötä.

Korjaava toimenpide. Näistä kiintiöistä ei neuvotella, ja pyynnön toistaminen palauttaa saman hylkäyksen. Nollaa testiympäristö toimistotilastasi — se palaa alkuperäisiin demotietoihin — tai tilaa palvelu: nämä kiintiöt koskevat vain testiympäristöjä.

Sinetöity aineisto: rekisteri on jäädytetty

Sinetöinti jäädyttää aineiston eheysketjun — juuri siinä on sen todistusarvo. Sinetöityä aineistoa ei voi enää muokata, se ei enää vastaanota asiakirjoja eikä sitä enää uudelleenseulota tätä kautta. Vain hälytyksen kvalifiointi on yhä mahdollista: se kirjoitetaan ketjun ulkopuolelle, sinetöity kärki ei koskaan liiku.

Korjaava toimenpide. Ei mitään ”korjattavaa”: tämä on tarkoituksellista muuttumattomuutta. Jos tietojen on muututtava, kyse on uudesta huolellisuustoimesta sovelluksessa, ei sinetöidyn aineiston muuttamisesta.

Suljettu aineisto: asiakassuhde on päättynyt

Suhde päätettiin sovelluksessa: aineisto ei enää vastaanota kirjoituksia API:n kautta — ei muokkausta, ei asiakirjaa, ei seulontaa eikä tosiasiallisia edunsaajia. Luku pysyy avoimena: suljettua aineistoa voi tarkastella ja viedä koko säilytysajan.

Korjaava toimenpide. Suhteen avaaminen uudelleen on ihmisen tekemä, lokiin kirjattu toimi sovelluksessa; API ei tee sitä puolestasi. Jos operaatio on uusi, avaa uusi aineisto sen sijaan että elvytät vanhan.

Poistettu aineisto: tiedot on pyyhitty

Säilytysaika on kulunut umpeen ja aineiston tiedot on pyyhitty. Jäljelle jää vain auditointijälki, joka todistaa, että aineisto oli olemassa ja että se poistettiin mainittuna päivänä; se ei enää vastaanota mitään kirjoitusta.

Korjaava toimenpide. Ei mitään korjattavaa eikä toistettavaa: poisto on lopullinen ja tarkoituksellinen. Järjestelmiisi jäänyt poistetun aineiston tunniste on historiaa, ei koskaan kirjoituksen kohde.

Asiakirjan muotoa ei hyväksytä

Todentavat asiakirjat hyväksyvät muodot PDF, JPG, JPEG, PNG ja WEBP — samat kuin sovelluksessa. Tarkistus kohdistuu pakollisen filename-kentän tiedostopäätteeseen: asiakirja ilman kelvollista tiedostonimeä hylätään sisällöstä riippumatta.

Korjaava toimenpide. Muunna ennen lähetystä (TIFF- tai HEIC-skannaus muuntuu PDF:ksi tai JPEG:ksi) ja lähetä sisältö tavallisena base64:nä contenu-kentässä, type-arvona jokin vakaista a_doc_*-koodeista.

Yli 6 Mt:n asiakirja

Raja koskee dekoodattua tiedostoa (6 Mt), samoin kuin sovelluksessa ja keräysportaalissa. Koska base64 lisää kolmanneksen koodauskuormaa, pyynnön runko hyväksyy enintään 9 Mt.

Korjaava toimenpide. Pakkaa asiakirja (värillinen 300 dpi:n skannattu PDF putoaa harmaasävyisenä lähes aina rajan alle) sen sijaan, että jakaisit sen osiin.

Seulontalähde ei käytettävissä

Yhtäkään aineiston entiteettiä ei voitu tarkistaa listoja vasten: lähde (virallisten listojen indeksi tai palveluntarjoaja) ei vastannut. API kieltäytyy tekemästä johtopäätöstä — ”puhdas” raportti kuolleen lähteen päällä olisi pahin mahdollinen väärä negatiivinen. Häiriö kirjataan aineistoon (erreurSource). Osittainen katko ei tuota tätä 502-vastausta: 200-vastaus säilyttää vastanneiden entiteettien osumat ja nimeää epäonnistuneet erreurSourceEntites-kentässä.

Korjaava toimenpide. Toista sama kutsu myöhemmin samalla Idempotency-Key-otsakkeella: idempotenssi muistaa vain onnistuneet vastaukset — virheen jälkeen toistettu kutsu suorittaa todellisen seulonnan.

Upotetut widgetit eivät ole käytössä tässä instanssissa

Myöntö POST /api/v1/embed/jetons nojaa toimiston ilmoittamiin alkuperiin — juuri tämä luettelo ohjaa upotetun shellin frame-ancestors-CSP:tä. Tämä 501 kertoo, ettei kutsumasi instanssi kanna tätä tallennusta: upotuspinta on siellä rakenteellisesti toimimaton, ja se sanoo näin sen sijaan, että myöntäisi tunnisteen, jota mikään alkuperä ei voisi koskaan näyttää. Ei pidä sekoittaa 400-vastaukseen, joka annetaan toimistolle, jonka alkuperiä ei ole vielä ilmoitettu.

Korjaava toimenpide. Tämä 501 koskee instanssia, ei pyyntöäsi. Osoitteessa vigilae.org toimiston pääkäyttäjä ilmoittaa alkuperät itse, näytöllä ”Integraatiot ja tietoturva” (widgetit-osion laatikko kertoo, missä); toista sitten sama kutsu. Koodissasi ei ole mitään korjattavaa: pyyntö oli kunnossa, instanssi ei ollut valmis.

Pinta ei ole käytettävissä tässä asennuksessa

Kaksi perustason lukua — GET /api/v1/dossiers/{id}/origine-fonds ja GET /api/v1/dossiers/{id}/exigences — nojaavat tallennustiloihin, joita jokainen instanssi ei kanna. Kun jokin puuttuu, API sanoo sen sen sijaan että palauttaisi tyhjän listan: ”ei huomautettavaa” ja ”mitään ei luettu” ovat vastakkaisia tosiasioita, ja niiden sekoittaminen saisi asian, jota kukaan ei ole katsonut, näyttämään asialta ilman huomautuksia. Tämä 501 koskee kutsuttua instanssia, ei koskaan pyyntöäsi eikä asiaa.

Korjaava toimenpide. Älä toista kutsua silmukassa: mikään ei muutu ennen kuin instanssi kantaa kyseisen tallennustilan. Käsittele koodia merkityksessä ”tieto ei ole täällä saatavilla” äläkä ennen kaikkea laske sitä nollaksi koosteissasi — juuri niin puuttuvasta mittauksesta tulee väärä luku. Vigilae.org-palvelussa molemmat luvut palvellaan; omassa asennuksessa tallennustilan päivitys kuuluu ylläpitäjällesi.