Katra kļūda, izskaidrota stabilā adresē.
Šī lapa ir darbības uzziņa, nevis reklāma. Katrai Connect API kļūdu klasei šeit ir pastāvīgs enkurs; API kļūdu atbildes norādīs uz šīm adresēm. Jūs saņemat iespējamo cēloni un risinājumu — tieši šādā secībā. Atpakaļ uz izstrādātāju dokumentāciju.
Atslēga trūkst, ir nepareizi formēta vai nezināma
API autentificē vienīgi ar galveni Authorization: Bearer vgk_… — nekad ar sesijas sīkdatni. Atsaukta atslēga kļūst nezināma tajā pašā mirklī, kad to atsauc.
Risinājums. Pārbaudiet, vai galvene tiešām tiek izsūtīta (starpnieki to reizēm noņem), vai atslēga sākas ar vgk_ un vai tā nav atsaukta biroja konsolē. Tā kā noslēpums tiek parādīts tikai izveides brīdī, pazaudētu atslēgu aizstāj, nevis atgūst.
Atslēgai beidzies termiņš
Katras atslēgas termiņš beidzas gadu pēc izveides — datums expire_le biroja konsolē ir redzams no pirmās dienas. Termiņa beigu 401 ir nepārprotams: tas pasaka, ka atslēga pastāvēja un vairs nav derīga.
Risinājums. Izveidojiet jaunu atslēgu, pārslēdziet uz to savus izsaukumus, atsauciet veco. Ieplānojiet šo nomaiņu savā darbībā, nevis atklājiet to pēkšņi: datums ir zināms gadu iepriekš.
Nepietiekams tvērums
Atslēgas nes lecture (lasīšana, noklusējums) un/vai ecriture (rakstīšana). Notikuma kvalificēšanai vajadzīgs ecriture; tikai lasoša atslēga saņem 403 neatkarīgi no resursa.
Risinājums. Izveidojiet atslēgu ar vajadzīgo tvērumu — un tikai ar to. Mazāko privilēģiju princips ir apzināts: integrācijai, kas tikai lasa, nav iemesla turēt rakstīšanas atslēgu.
Nav atrasts — vai pieder citam birojam
404 nozīmē, ka resurss nepastāv vai pieder citam birojam. API šos divus gadījumus nekad nenošķir: nošķiršana atklātu, kas pastāv citur. Nodalīšana tiek uzturēta datubāzes līmenī, ne tikai lietojumprogrammas kodā.
Risinājums. Pārbaudiet seq pret tā biroja žurnālu, kuram atslēga pieder (GET /api/v1/evenements). Ja integrējat vairākus birojus, katram birojam ir savas atslēgas: seq starp birojiem neceļo.
Pārsniegts pieprasījumu limits
60 pieprasījumi minūtē uz atslēgu pēc noklusējuma (pielāgojams katrai atslēgai). Atbilde nes Retry-After un galvenes X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.
Risinājums. Ievērojiet Retry-After — nekādas tūlītējas atkārtošanas. Limita sasniegšana aptaujas laikā gandrīz vienmēr liecina par pilnu atkārtotu skenēšanu: kursors depuisSeq nekad nepārlasa jau izlasīto.
Paraksts jūsu pusē neapstiprinās
Jūsu saņēmējam jāpārrēķina v1 = HMAC-SHA256(secret, t + "." + body) no saņemtā neapstrādātā ķermeņa un jānoraida jebkurš t, kas vecāks par 5 min. Klasiskās kļūmes: ķermenis pirms pārbaudes serializēts no jauna (pārformatētam JSON vairs nav to pašu baitu), pulkstenis, kas nobīdījies ārpus pielaides, un ignorēta rotācija — 24 h galvene nes vienu v1 katram vēl derīgajam noslēpumam, un jāpieņem, ja sakrīt jebkurš no tiem.
Risinājums. Pārbaudiet pret neapstrādātajiem baitiem, sinhronizējiet pulksteni (NTP), izmēģiniet savu pārbaudi rotācijas laikā. Node un Python fragmenti dokumentācijā dara tieši to — kopējiet tos, nevis rakstiet no jauna.
Notikums pienāk divreiz
Piegāde ir at-least-once, partijās pa ne vairāk kā 100, žurnāla secībā; kursors virzās uz priekšu tikai pēc jūsu 2xx, partiju pa partijai. Kļūme pēc saņemšanas, bet pirms kursora pavirzīšanās izraisa atkārtotu piegādi — tas ir līgums, nevis defekts.
Risinājums. seq ir jūsu idempotences atslēga: apstrādājiet katru secību tieši vienu reizi un atbildiet 2xx tikai pēc saglabāšanas. Pāragrs 2xx, kam seko avārija, ir vienīgais veids, kā pazaudēt notikumu.
Žurnāls izskatās nepilnīgs vai atkārtojas
depuisSeq ir strikti izslēdzošs: tiek atgriezti tikai notikumi ar lielāku seq, kārtoti augoši, ne vairāk kā 500 lapā. Atbilde atgriež prochainSeq, ko nodod tālāk nemainītu. Lapa, kas īsāka par limite, nozīmē žurnāla beigas.
Risinājums. Saglabājiet prochainSeq starp izpildēm un nekad nepārrēķiniet to paši. Dublikāti nozīmē, ka atsākāt no pārāk veca kursora; robi — ka izlaidāt neizdevušos lapu, to neatkārtojot.
Parametrs ārpus shēmas
Nezināms statuss, risinājums ārpus saraksta (planifie, traite, ecarte), limite, kas nav vesels skaitlis: atbilde nosauc kļūdaino lauku un neko citu — kļūdu ziņojumi nekad nenes lietas saturu.
Risinājums. OpenAPI specifikācija ir avots: tās deklarētie uzskaitījumi un robežas ir tie, ko serveris piemēro, jo specifikāciju pasniedz pats serveris.
Nepietiekams tvērums (resursu API)
Resursu galapunktiem (/clients, /dossiers, dokumenti, pārbaude pret sarakstiem, brīdinājumi) vajadzīgs precīzs tvērums: clients:*, dossiers:*, pieces:*, criblage:* vai īpašais tvērums alertes:qualifier. Vēsturiska lecture atslēga piešķir visus *:lecture tvērumus, un ecriture — visus *:ecriture, taču alertes:qualifier nekad netiek mantots: brīdinājuma kvalificēšana ir atbildīgās personas rīcība, ko deleģē, atzīmējot šo tvērumu atslēgas izveides brīdī.
Risinājums. Izveidojiet atslēgu tieši ar tiem tvērumiem, kas jūsu integrācijai vajadzīgi — un tikai ar tiem. Atbildes lauks detail nosauc trūkstošo tvērumu.
Resurss nav atrasts — vai pieder citam birojam
Tas pats noteikums kā #cloisonnement, piemērots resursiem: klients, lieta, dokuments vai brīdinājums, kas nepastāv vai pieder citam birojam, saņem to pašu 404. API šos divus gadījumus nekad nenošķir.
Risinājums. Pārbaudiet identifikatoru pret tā biroja sarakstiem, kuram atslēga pieder. Identifikators nekad neceļo no viena biroja uz citu.
Trūkst galvenes Idempotency-Key
Katram POST, kas izveido vai iedarbina (klients, lieta, dokuments, pārbaude, patiesie labuma guvēji), vajadzīga galvene Idempotency-Key: stabila virkne, ne garāka par 200 rakstzīmēm, viena katrai operācijai. Tās pašas atslēgas atkārtošana ar to pašu ķermeni atgriež to pašu atbildi bez jebkādas iedarbības — jūsu aizsardzība pret dublikātiem tīkla incidenta gadījumā.
Risinājums. Ģenerējiet atslēgu pirms pirmā mēģinājuma (viens UUID katrai biznesa operācijai) un izmantojiet to nemainītu katrā šīs pašas operācijas atkārtojumā.
Idempotences atslēga atkārtoti izmantota ar citu ķermeni
Šī Idempotency-Key pēdējo 24 stundu laikā jau ir izmantota ar citu ķermeni. Atslēga atkārto atbildi, tā nekad to nepārraksta: tās atkārtota izmantošana jaunai operācijai gandrīz vienmēr liecina par atslēgu, kas atvasināta no skaitītāja vai no apcirsta datuma.
Risinājums. Jauna atslēga katrai jaunai operācijai. Nekad neatvasiniet atslēgu no datiem, kas dažādās operācijās atkārtojas.
Aizzīmogota lieta: reģistrs ir iesaldēts
Aizzīmogošana iesaldē lietas integritātes ķēdi — tā ir tās pierādījuma vērtība. Aizzīmogotu lietu vairs nevar rediģēt, tā vairs nesaņem dokumentus un pa šo kanālu vairs netiek atkārtoti pārbaudīta. Iespējama paliek tikai brīdinājumu kvalificēšana: to raksta off-chain, aizzīmogotā galva nekad nekustas.
Risinājums. Nav ko „labot”: tā ir apzināta nemainība. Ja datiem jāmainās, tā ir jauna uzticamības pārbaudes operācija lietojumprogrammā, nevis aizzīmogotās lietas mutācija.
Dokumenta formāts netiek pieņemts
Apliecinošajiem dokumentiem tiek pieņemti PDF, JPG, JPEG, PNG un WEBP — tie paši formāti kā lietojumprogrammā. Pārbaude notiek pēc obligātā filename paplašinājuma: dokuments bez derīga faila nosaukuma tiek noraidīts neatkarīgi no satura.
Risinājums. Konvertējiet pirms sūtīšanas (TIFF vai HEIC skenējumu konvertē uz PDF vai JPEG) un sūtiet saturu kā standarta base64 laukā contenu ar type no stabilajiem a_doc_* kodiem.
Dokuments lielāks par 6 MB
Ierobežojums attiecas uz atkodēto failu (6 MB) — tāpat kā lietojumprogrammā un dokumentu savākšanas portālā. Tā kā base64 pievieno trešdaļu kodēšanas piedevas, pieprasījuma ķermenis pieņem līdz 9 MB.
Risinājums. Saspiediet dokumentu (krāsains 300 dpi skenēts PDF pelēktoņos gandrīz vienmēr nokrīt zem robežas), nevis sadaliet to.
Pārbaudes avots nav pieejams
Nevienu no lietas subjektiem nevarēja pārbaudīt pret sarakstiem: avots (oficiālo sarakstu indekss vai piegādātājs) neatbildēja. API atsakās izdarīt secinājumu — „tīrs” ziņojums uz miruša avota pamata būtu sliktākais iespējamais viltus negatīvais rezultāts. Kļūme tiek reģistrēta lietā (erreurSource). Daļējs pārtraukums šo 502 nerada: 200 atbilde patur atbildējušo subjektu atbilsmes un laukā erreurSourceEntites nosauc tos, kuru pārbaude neizdevās.
Risinājums. Atkārtojiet to pašu izsaukumu vēlāk, ar to pašu Idempotency-Key: idempotence saglabā atmiņā tikai veiksmīgās atbildes — atkārtošana pēc kļūdas veic reālu pārbaudi.
Šī lapa attīstīsies līdz ar API; esošie enkuri tomēr nekad nemaina adresi — varat tos glabāt savos darbības žurnālos.