Iga viga, selgitatud püsival aadressil.
See leht on tööteatmik, mitte müügijutt. Connecti API igal veaklassil on siin püsiv anker; API veavastused osutavad nendele aadressidele. Te saate tõenäolise põhjuse ja paranduse — just selles järjekorras. Tagasi arendajate dokumentatsiooni juurde.
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.
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.
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.
Parandus. Looge uus võti, suunake oma päringud sellele ümber, tühistage vana. Kavandage see asendus oma töökorraldusse, selle asemel et seda avastada: kuupäev on teada aasta ette.
Ebapiisav skoop
Võtmed kannavad skoopi lecture (lugemine, vaikimisi) ja/või ecriture (kirjutamine). Sündmuse kvalifitseerimine nõuab skoopi ecriture; ainult lugemisõigusega võti saab 403, olgu ressurss milline tahes.
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.
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.
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.
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.
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.
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.
See leht areneb koos API-ga; olemasolevad ankrud aga ei vaheta kunagi aadressi — võite need oma töölogidesse talletada.