Katra kļūda, izskaidrota stabilā adresē.

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.

Tas pats 401 satur "motif": "fin_option_api", ja atslēga ir pārtraukta, jo API vairs nav iekļauta biroja abonementā. Šīs pārtraukšanas datums tika norādīts e-pasta ziņojumā biroja administratoriem vai, ja tādu nav, uz biroja norēķinu adresi un pēc tam paziņots katras atbildes uz pieņemtu izsaukumu galvenē Sunset (grafiks: #cle-expiree). Bez motīva tas var rasties arī apturēta abonementa dēļ: apturēšana atslēgas pārtrauc nekavējoties.

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. Ja atbildē ir "motif": "fin_option_api", vaina nav ne galvenē, ne atslēgā: biroja administrators raksta mums uz contact@vigilae.org, lai API atkal tiktu iekļauta abonementā, un tā pati atslēga atkal tiek pieņemta, tiklīdz tas izdarīts, līdz tās pašas derīguma termiņa beigām.

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.

API atslēgu var pārstāt pieņemt arī pirms šī datuma, ja API vairs nav iekļauta biroja abonementā. Pārtraukšana tad notiek vismaz 30 dienas pēc pirmā e-pasta ziņojuma, datumā, ko norāda otrs e-pasta ziņojums, kas nosūtīts vismaz 7 dienas iepriekš; abi tiek sūtīti biroja administratoriem vai, ja tādu nav, uz biroja norēķinu adresi. Tiklīdz šis datums ir noteikts, tas redzams biroja konsolē (GET /connect/cles lauks coupure_le), un katra atbilde uz pieņemtu izsaukumu to paziņo galvenē Sunset, līdz tas pienāk. Pēc šī datuma izsaukums saņem 401, kas aprakstīts sadaļā #authentification, ar "motif": "fin_option_api"; ja API atkal tiek iekļauta abonementā, atslēga atkal tiek pieņemta līdz tās pašas derīguma termiņa beigām.

Risinājums. Izveidojiet jaunu atslēgu, pārslēdziet uz to savus izsaukumus, atsauciet veco. API atslēgai vajag, lai API joprojām būtu iekļauta biroja abonementā: bez tās konsole atsakās izveidot atslēgu. Ieplānojiet šo nomaiņu savā darbībā, nevis atklājiet to pēkšņi.

Nepietiekams tvērums

Atslēgas nes tvērumus, kas atzīmēti to izveidē: vispārīgos lecture (lasīšana, noklusējums) un ecriture (rakstīšana) vai smalkos pa resursiem (clients:lecture, pieces:ecriture, origine-fonds:lecture, journal:lecture…).

Mantošana balstās uz piedēkli, tikai vienā virzienā: lecture aptver katru *:lecture, ecriture — katru *:ecriture; otrādi nekad, smalks tvērums atver tikai pats sevi.

Seši tvērumi iziet ārpus šī pāra un netiek mantoti ne no vienas vispārīgas atslēgas: alertes:qualifier, embed:emettre, adversemedia:consulter, conformite:consulter, dispositif:consulter, integrite:consulter. Notikuma kvalificēšana, iegulšanas pilnvaras izdošana, lietas nelabvēlīgās preses vai lietas kārtošanas vērtējuma lasīšana nekad neizriet no vispārīgām lasīšanas tiesībām: katrs tiek atzīmēts atsevišķi.

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, un plaša atslēga nekad neaizstās tvērumu, kas nav deleģēts tieši.

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.

Šis konts jau pastāv

POST /scim/v2/Users uz userName, kas šim birojam jau ir izveidots, atbild ar 409 un scimType: uniqueness. Unikalitāti tur datubāzes ierobežojums, nevis kešatmiņa: divas vienlaicīgas izveides nevar radīt divus kontus.

Risinājums. Uztveriet 409 kā idempotentu veiksmi, nevis kļūdu: nolasiet kontu ar ?filter=userName eq "…" un turpiniet ar atgriezto identifikatoru. Savienotājs, kas pēc 409 atkārto ciklā, nekad neizveidos neko vairāk.

Šis konts atrodas ārpus direktorija sniedzamības

Direktorijs nevar ne pazemināt, ne atspējot kontu, kam ir biroja administrēšanas pilnvaras: pieprasījums tiek noraidīts ar scimType: mutability un reģistrēts. Bez šīs robežas savienotājs, kas pārņem par atbilstību atbildīgās personas adresi, aizvērtu biroju tieši tam, kurš par to atbild.

Risinājums. Izņemiet šo personu no sinhronizētā tvēruma vai mainiet tās lomu pašā Vigilae. Atteikums attiecas tikai uz šo kontu: pārējā partijas daļa tiek piemērota parastā kārtībā.

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.

Lauks, kura vērtība ir pārāk gara: Pilsonība

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.

Cits mēģinājums ar šo atslēgu vēl tiek izpildīts

Divi pieprasījumi ar vienu un to pašu Idempotency-Key pienāca vienlaikus: pirmais tiek izpildīts, otrais tiek atteikts pirms jebkādas iedarbības. Tieši šis atteikums novērš dublikātu. Parastais gadījums: starpniekserveris atbild ar 502 vai 504, kamēr serveris vēl strādā, un jūsu klients pieprasījumu atkārto. Galvene Retry-After norāda, pēc cik sekundēm to atkārtot.

Risinājums. Atkārtojiet to pašu pieprasījumu bez izmaiņām, ar to pašu atslēgu, pēc norādītās gaidīšanas: jūs saņemsiet pirmā mēģinājuma atbildi. Nekad neveidojiet jaunu atslēgu, lai „atbloķētu” — tas radītu tieši to dublikātu, ko atslēga novērš.

Testa vide: kvota ir sasniegta

Testa videi ir fiksēti ierobežojumi: 200 klientu profili, 50 lietas un 40 dokumenti katrā lietā. Izveide vai augšupielāde, kas pārsniegtu kādu no tiem, tiek atteikta pirms jebkāda ieraksta, un atteikums norāda, kurš ierobežojums ir sasniegts: lauki ressource, quota un courant satur resursu, augšējo robežu un skaitu atteikuma brīdī. Ja divas vienlaicīgas izveides sacenšas par pēdējo vietu, tiek izpildīta tikai viena. Esoša klienta profila vai lietas rediģēšana kvotu nepatērē.

Risinājums. Šīs kvotas nav apspriežamas, un pieprasījuma atkārtošana atgriezīs to pašu atteikumu. Atiestatiet testa vidi savā darbvietā — tā sāk no jauna ar demonstrācijas datiem — vai noformējiet abonementu: šīs kvotas attiecas tikai uz testa vidēm.

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.

Slēgta lieta: darījuma attiecības ir izbeigtas

Attiecības tika izbeigtas lietojumprogrammā: lieta vairs nepieņem ierakstus caur API — ne rediģēšanu, ne dokumentu, ne pārbaudi, ne patiesos labuma guvējus. Lasīšana paliek atvērta: slēgtu lietu var apskatīt un eksportēt visu glabāšanas laiku.

Risinājums. Attiecību atkārtota atvēršana ir cilvēka veikta, reģistrēta darbība lietojumprogrammā; API to jūsu vietā neizdara. Ja darbība ir jauna, atveriet jaunu lietu, nevis atdzīviniet veco.

Dzēsta lieta: dati ir izņemti

Glabāšanas termiņš ir beidzies un lietas dati ir dzēsti. Paliek tikai audita pēda, kas apliecina, ka lieta ir bijusi un ka tā norādītajā datumā dzēsta; tā vairs nepieņem nevienu ierakstu.

Risinājums. Nav ko labot un nav ko atkārtot: dzēšana ir galīga un apzināta. Jūsu sistēmās saglabāts dzēstas lietas identifikators ir vēsture, nekad ieraksta mērķis.

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.

Iegultie logrīki nav aktivizēti šajā instancē

Mint POST /api/v1/embed/jetons balstās uz jūsu biroja deklarētajām izcelsmēm — tieši šis saraksts vada iegultā apvalka frame-ancestors CSP direktīvu. Šis 501 saka, ka izsauktā instance nesatur šo krātuvi: embed virsma tur pēc uzbūves ir inerta, un tā to saka, nevis izsniedz marķieri, ko neviena izcelsme nekad nevarētu attēlot. Nejaukt ar 400, ko saņem birojs, kura izcelsmes vēl nav deklarētas.

Risinājums. Šis 501 attiecas uz instanci, nevis uz jūsu pieprasījumu. Vietnē vigilae.org jūsu biroja administrators pats deklarē izcelsmes ekrānā „Integrācijas un drošība” (kur — to rāda ietvars logrīku sadaļā); tad atkārtojiet to pašu izsaukumu. Jūsu kodā nav nekas jālabo: pieprasījums bija pareizs, instance nebija gatava.

Virsma šajā izvietojumā nav pieejama

Divi pamata lasījumi — GET /api/v1/dossiers/{id}/origine-fonds un GET /api/v1/dossiers/{id}/exigences — balstās uz krātuvēm, kuras nav katrā instancē. Kad kādas trūkst, API to pasaka, nevis atdod tukšu sarakstu: „nav ko ziņot” un „nekas netika nolasīts” ir pretēji fakti, un to sajaukšana liktu lietai, kurā neviens nav ieskatījies, izskatīties pēc lietas bez piezīmēm. Šis 501 runā par izsaukto instanci, nekad par jūsu pieprasījumu vai lietu.

Risinājums. Neatkārtojiet izsaukumu ciklā: nekas nemainīsies, kamēr instancē nebūs šīs krātuves. Uztveriet kodu kā „dati šeit nav pieejami” un galvenokārt neuzskaitiet to kā nulli savos paneļos — tieši tā trūkstošs mērījums kļūst par nepareizu skaitli. Vietnē vigilae.org abi lasījumi tiek apkalpoti; īpašā izvietojumā krātuves atjaunināšana ir jūsu operatora ziņā.