Jokainen virhe, selitettynä pysyvässä osoitteessa.
Tämä sivu on käyttöviite, ei myyntipuhe. Jokaisella Connect-API:n virheluokalla on täällä pysyvä ankkuri; API:n virhevastaukset osoittavat näihin osoitteisiin. Saat todennäköisen syyn ja korjaavan toimenpiteen — tässä järjestyksessä. Takaisin kehittäjädokumentaatioon.
Avain puuttuu, on virheellinen tai tuntematon
API todentaa yksinomaan Authorization: Bearer vgk_… -otsakkeella — ei koskaan istuntoevästeellä. Peruttu avain muuttuu tuntemattomaksi perumishetkellä.
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.
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.
Korjaava toimenpide. Luo uusi avain, siirrä kutsusi sille, peru vanha. Suunnittele vaihto osaksi operaatioitasi sen sijaan, että huomaisit sen yllätyksenä: päivämäärä on tiedossa vuotta aiemmin.
Riittämätön scope
Avaimet kantavat scopet lecture (luku, oletus) ja/tai ecriture (kirjoitus). Tapahtuman kvalifiointi vaatii ecriture-scopen; pelkän lukuoikeuden avain saa 403-vastauksen resurssista riippumatta.
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.
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.
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.
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.
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.
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.
Tämä sivu kehittyy API:n mukana; olemassa olevat ankkurit eivät kuitenkaan koskaan vaihda osoitetta — voit tallettaa ne operaatiolokeihisi.