Kiekviena klaida, paaiškinta stabiliu adresu.
Šis puslapis — operacijų žinynas, ne reklama. Kiekviena Connect API klaidų klasė čia turi nuolatinį inkarą; API klaidų atsakymai rodys būtent į šiuos adresus. Gaunate tikėtiną priežastį ir ką daryti — būtent tokia tvarka. Grįžti į kūrėjų dokumentaciją.
Rakto nėra, jis netinkamo formato arba nežinomas
API autentifikuoja tik per antraštę Authorization: Bearer vgk_… — niekada per sesijos slapuką. Atšauktas raktas tampa nežinomas tą pačią akimirką, kai atšaukiamas.
Ką daryti. Patikrinkite, ar antraštė iš tiesų išsiunčiama (tarpiniai serveriai kartais ją nukerpa), ar raktas prasideda vgk_ ir ar jis nebuvo atšauktas iš biuro konsolės. Kadangi paslaptis parodoma tik kuriant, pamestas raktas keičiamas nauju, o ne atkuriamas.
Pasibaigusio galiojimo raktas
Kiekvieno rakto galiojimas baigiasi po metų nuo sukūrimo — data expire_le biuro konsolėje matoma nuo pirmos dienos. Galiojimo pabaigos 401 yra aiškus: jis sako, kad raktas egzistavo ir nebegalioja.
Ką daryti. Sukurkite naują raktą, perjunkite į jį savo iškvietimus, atšaukite senąjį. Šį pakeitimą planuokite savo operacijose, o ne atraskite netikėtai: data žinoma metus į priekį.
Nepakankama aprėptis
Raktai turi aprėptis lecture (skaitymas, numatytoji) ir (arba) ecriture (rašymas). Įvykiui kvalifikuoti reikia ecriture; tik skaitantis raktas gauna 403, kad ir koks būtų išteklius.
Ką daryti. Sukurkite raktą su reikiama aprėptimi — ir tik su ja. Mažiausios privilegijos čia sąmoningos: integracija, kuri tik skaito, neturi jokios priežasties laikyti rašymo rakto.
Nerasta — arba priklauso kitam biurui
404 reiškia, kad išteklius neegzistuoja arba priklauso kitam biurui. API šių dviejų atvejų niekada neskiria: skirti reikštų atskleisti, kas egzistuoja kitur. Atskyrimas užtikrinamas duomenų bazės lygmeniu, ne vien programos kode.
Ką daryti. Patikrinkite seq pagal to biuro, kuriam priklauso raktas, žurnalą (GET /api/v1/evenements). Jei integruojate kelis biurus, kiekvienas biuras turi savus raktus: seq tarp biurų nekeliauja.
Viršyta užklausų sparta
60 užklausų per minutę vienam raktui pagal numatytuosius nustatymus (galima keisti kiekvienam raktui atskirai). Atsakymas neša Retry-After ir antraštes X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.
Ką daryti. Gerbkite Retry-After — jokio kartojimo iškart. Į ribą atsitrenkiama apklausiant beveik visada dėl pilno pernuskaitymo: žymeklis depuisSeq niekada neskaito iš naujo to, kas jau perskaityta.
Parašas jūsų pusėje nepasitvirtina
Jūsų gavėjas privalo perskaičiuoti v1 = HMAC-SHA256(secret, t + "." + body) iš gauto neapdoroto kūno ir atmesti bet kokį t, senesnį nei 5 min. Klasikiniai nesklandumai: kūnas prieš tikrinimą serializuotas iš naujo (performatuotas JSON nebeturi tų pačių baitų), laikrodis, nuslinkęs už tolerancijos ribos, ir ignoruota rotacija — 24 val. antraštėje yra po vieną v1 kiekvienai dar galiojančiai paslapčiai, ir priimti privalote, jei sutampa bent viena.
Ką daryti. Tikrinkite pagal neapdorotus baitus, sinchronizuokite laikrodį (NTP), išbandykite savo tikrinimą rotacijos metu. Node ir Python fragmentai dokumentacijoje daro būtent tai — kopijuokite juos, užuot rašę iš naujo.
Įvykis atkeliauja du kartus
Pristatymas yra at-least-once, paketais ne didesniais kaip 100, žurnalo tvarka; žymeklis pasislenka tik gavus jūsų 2xx, paketas po paketo. Gedimas po gavimo, bet prieš žymekliui pasislenkant, sukelia pakartotinį pristatymą — tai kontraktas, o ne defektas.
Ką daryti. seq yra jūsų idempotencijos raktas: kiekvieną seką apdorokite lygiai vieną kartą ir 2xx atsakykite tik įrašę į saugyklą. Per ankstyvas 2xx ir po jo įvykęs strigimas — vienintelis būdas prarasti įvykį.
Žurnalas atrodo neišsamus arba kartojasi
depuisSeq yra griežtai išskirtinis: grąžinami tik įvykiai su didesniu seq, surikiuoti didėjančia tvarka, ne daugiau kaip 500 puslapyje. Atsakymas grąžina prochainSeq, kurį perduodate nepakeistą. Puslapis, trumpesnis už limite, reiškia žurnalo pabaigą.
Ką daryti. Saugokite prochainSeq tarp paleidimų ir niekada neperskaičiuokite jo patys. Dublikatai reiškia, kad startavote nuo per seno žymeklio; spragos — kad praleidote nepavykusį puslapį jo nepakartoję.
Parametras už schemos ribų
Nežinoma būsena, sprendimas ne iš sąrašo (planifie, traite, ecarte), nesveikaskaitinis limite: atsakymas įvardija netinkamą lauką ir nieko daugiau — klaidų pranešimai niekada neneša bylų turinio.
Ką daryti. OpenAPI specifikacija yra šaltinis: jos deklaruojami išvardijimai ir ribos yra tie patys, kuriuos taiko serveris, nes ją pateikia jis pats.
Nepakankama aprėptis (išteklių API)
Išteklių galiniams taškams (/clients, /dossiers, dokumentai, patikra, įspėjimai) reikia smulkiosios aprėpties: clients:*, dossiers:*, pieces:*, criblage:* arba skirtosios aprėpties alertes:qualifier. Senasis raktas lecture suteikia visas *:lecture aprėptis, o ecriture — visas *:ecriture, tačiau alertes:qualifier niekada nepaveldima: įspėjimo kvalifikavimas yra atsakingo asmens veiksmas, deleguojamas pažymint šią aprėptį kuriant raktą.
Ką daryti. Sukurkite raktą tiksliai su tomis aprėptimis, kurių reikia jūsų integracijai — ir tik su jomis. Atsakymo detail įvardija trūkstamą aprėptį.
Išteklius nerastas — arba priklauso kitam biurui
Ta pati taisyklė kaip #cloisonnement, taikoma ištekliams: klientas, byla, dokumentas ar įspėjimas, kuris neegzistuoja arba priklauso kitam biurui, gauna tą patį 404. API šių dviejų atvejų niekada neskiria.
Ką daryti. Patikrinkite identifikatorių pagal to biuro, kuriam priklauso raktas, sąrašus. Identifikatorius niekada nekeliauja iš vieno biuro į kitą.
Trūksta Idempotency-Key antraštės
Kiekvienam kuriančiam ar paleidžiančiam POST (klientas, byla, dokumentas, patikra, tikrieji savininkai) reikia antraštės Idempotency-Key: stabili eilutė, ne ilgesnė kaip 200 ženklų, po vieną kiekvienai operacijai. Pakartojus tą patį raktą su tuo pačiu kūnu, grąžinamas tas pats atsakymas be jokio poveikio — jūsų apsauga nuo dublikatų per tinklo incidentą.
Ką daryti. Sugeneruokite raktą prieš pirmą bandymą (po vieną UUID kiekvienai verslo operacijai) ir naudokite jį nepakeistą kiekvienam tos pačios operacijos pakartojimui.
Idempotencijos raktas pakartotas su kitu kūnu
Šis Idempotency-Key per pastarąsias 24 valandas jau buvo panaudotas kitam kūnui. Raktas pakartoja atsakymą, jis niekada jo neperrašo: jo naudojimas naujai operacijai beveik visada rodo raktą, išvestą iš skaitiklio ar nukirstos datos.
Ką daryti. Naujas raktas kiekvienai naujai operacijai. Niekada neveskite rakto iš duomenų, kurie tarp operacijų kartojasi.
Užantspauduota byla: registras įšaldytas
Antspaudavimas įšaldo bylos vientisumo grandinę — būtent tai yra jos įrodomoji vertė. Užantspauduotos bylos nebegalima redaguoti, ji nebepriima dokumentų ir šiuo kanalu nebetikrinama pakartotinai. Lieka galimas tik įspėjimų kvalifikavimas: jis rašomas šalia grandinės, užantspauduota viršūnė niekada nejuda.
Ką daryti. Nėra ko „taisyti“: tai sąmoningas nekintamumas. Jei duomenys turi keistis, tai nauja deramo patikrinimo operacija programoje, o ne užantspauduotos bylos mutacija.
Nepriimtinas dokumento formatas
Patvirtinamieji dokumentai priimami PDF, JPG, JPEG, PNG ir WEBP formatais — tais pačiais kaip programoje. Tikrinamas privalomo filename plėtinys: dokumentas be tinkamo failo vardo atmetamas, kad ir koks būtų jo turinys.
Ką daryti. Konvertuokite prieš siųsdami (TIFF ar HEIC skenas konvertuojasi į PDF ar JPEG) ir siųskite turinį standartiniu base64 lauke contenu, su type iš stabilių a_doc_* kodų.
Dokumentas didesnis nei 6 MB
Riba taikoma dekoduotam failui (6 MB) — ta pati kaip programoje ir dokumentų surinkimo portale. Kadangi base64 prideda trečdalį kodavimo antsvorio, užklausos kūnas priima iki 9 MB.
Ką daryti. Suglaudinkite dokumentą (spalvotas 300 dpi skenuotas PDF pilkų tonų režimu beveik visada nusileidžia žemiau ribos), užuot jį skaidę.
Patikros šaltinis nepasiekiamas
Nė vieno bylos subjekto nepavyko sutikrinti su sąrašais: šaltinis (oficialių sąrašų indeksas arba tiekėjas) neatsakė. API atsisako daryti išvadą — „švari“ ataskaita ant mirusio šaltinio būtų pats blogiausias įmanomas klaidingai neigiamas rezultatas. Gedimas užfiksuojamas byloje (erreurSource). Dalinis sutrikimas šio 502 nesukelia: 200 atsakymas išsaugo atsakiusių subjektų atitikmenis, o neatsakiusius įvardija lauke erreurSourceEntites.
Ką daryti. Vėliau pakartokite tą patį iškvietimą su ta pačia Idempotency-Key: idempotencija įsimena tik sėkmės atsakymus — pakartojimas po klaidos paleidžia tikrą patikrą.
Šis puslapis kis kartu su API; tačiau esami inkarai niekada nekeičia adreso — galite juos saugoti savo operacijų žurnaluose.