Fiecare eroare, explicată la o adresă stabilă.

Cheie lipsă, malformată sau necunoscută

API-ul autentifică exclusiv prin antetul Authorization: Bearer vgk_… — niciodată printr-un cookie de sesiune. O cheie revocată devine necunoscută în clipa revocării.

Același 401 poartă "motif": "fin_option_api" atunci când cheia a fost oprită pentru că API-ul nu mai face parte din abonamentul cabinetului. Data acestei opriri a fost indicată într-un e-mail către administratorii cabinetului sau, în lipsa acestora, către adresa de facturare a cabinetului, apoi anunțată în antetul Sunset al fiecărui răspuns la un apel acceptat (calendarul la #cle-expiree). Fără motiv, poate proveni și dintr-un abonament suspendat: suspendarea întrerupe cheile pe loc.

Remediul. Verificați că antetul chiar pleacă (unele proxy-uri îl elimină), că cheia începe cu vgk_ și că nu a fost revocată din consola cabinetului. Cum secretul este afișat doar la creare, o cheie pierdută se înlocuiește, nu se recuperează. Cu "motif": "fin_option_api", nici antetul, nici cheia nu sunt de vină: administratorul cabinetului ne scrie la contact@vigilae.org pentru ca API-ul să revină în abonament, iar aceeași cheie este din nou acceptată de îndată ce acest lucru s-a făcut, până la propria ei dată de expirare.

Cheie expirată

Fiecare cheie expiră la un an de la creare — data expire_le este vizibilă în consola cabinetului din prima zi. 401-ul de expirare este explicit: spune că cheia a existat și că nu mai este validă.

O cheie API poate înceta să fie acceptată și înainte de această dată, atunci când API-ul nu mai face parte din abonamentul cabinetului. Oprirea intervine atunci la cel puțin 30 de zile după un prim e-mail, la data indicată de un al doilea e-mail, trimis cu cel puțin 7 zile înainte; ambele sunt trimise către administratorii cabinetului sau, în lipsa acestora, către adresa de facturare a cabinetului. Odată stabilită, această dată se poate citi în consola cabinetului (câmpul coupure_le din GET /connect/cles), iar fiecare răspuns la un apel acceptat o anunță în antetul Sunset până când sosește. După această dată, apelul primește 401-ul descris la #authentification, cu "motif": "fin_option_api"; dacă API-ul revine în abonament, cheia este din nou acceptată, până la propria ei dată de expirare.

Remediul. Creați o cheie nouă, mutați apelurile pe ea, revocați-o pe cea veche. Pentru o cheie API, este nevoie ca API-ul să facă încă parte din abonamentul cabinetului: fără el, consola refuză să creeze una. Planificați această înlocuire în operațiunile dumneavoastră în loc să o descoperiți.

Scope insuficient

Cheile poartă scope-urile bifate la crearea lor: cele generale lecture (citire, implicit) și ecriture (scriere) sau cele fine, pe resursă (clients:lecture, pieces:ecriture, origine-fonds:lecture, journal:lecture…).

Moștenirea urmează sufixul, într-un singur sens: lecture acoperă orice *:lecture, ecriture orice *:ecriture — niciodată invers; un scope fin deschide doar pe el însuși.

Șase scope-uri ies din această pereche și nu se moștenesc din nicio cheie generală: alertes:qualifier, embed:emettre, adversemedia:consulter, conformite:consulter, dispositif:consulter, integrite:consulter. Calificarea unui eveniment, emiterea unui token de încorporare, citirea presei nefavorabile a unui dosar sau a unei note de ținere a dosarului nu decurg niciodată dintr-un drept general de citire: fiecare se bifează separat.

Remediul. Creați o cheie care poartă scope-ul necesar — și doar pe acela. Privilegiul minim este deliberat: o integrare care doar citește nu are de ce să dețină o cheie de scriere, iar o cheie largă nu va suplini niciodată un scope care nu a fost delegat explicit.

Negăsit — sau al altui cabinet

Un 404 înseamnă că resursa nu există sau aparține altui cabinet. API-ul nu distinge niciodată cele două cazuri: a le distinge ar dezvălui ce există în altă parte. Izolarea este impusă la nivelul bazei de date, nu doar în codul aplicației.

Remediul. Verificați seq-ul în jurnalul cabinetului căruia îi aparține cheia (GET /api/v1/evenements). Dacă integrați mai multe cabinete, fiecare cabinet are propriile chei: un seq nu circulă între cabinete.

Acest cont există deja

Un POST /scim/v2/Users pe un userName deja provizionat pentru acest cabinet răspunde 409 cu scimType: uniqueness. Unicitatea este ținută de o constrângere a bazei de date, nu de o memorie tampon: două creări simultane nu pot produce două conturi.

Remediul. Tratați 409 ca pe un succes idempotent, nu ca pe o eroare: recitiți contul cu ?filter=userName eq "…" și continuați cu identificatorul returnat. Un conector care reîncearcă în buclă la un 409 nu va crea niciodată nimic în plus.

Acest cont este în afara razei directorului

Un director nu poate nici retrograda, nici dezactiva un cont care poartă puteri de administrare a cabinetului: cererea este refuzată cu scimType: mutability și consemnată. Fără această limită, un conector care preia adresa responsabilului cu conformitatea ar închide cabinetul tocmai celui care răspunde de el.

Remediul. Scoateți această persoană din perimetrul sincronizat sau schimbați-i rolul din Vigilae. Refuzul privește doar acest cont: restul lotului se aplică normal.

Debit depășit

60 de cereri pe minut per cheie, implicit (ajustabil per cheie). Răspunsul poartă Retry-After și antetele X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.

Remediul. Respectați Retry-After — fără reîncercare imediată. Atingerea limitei în timpul interogării periodice este aproape întotdeauna semnul unei rescanări complete: cursorul depuisSeq nu recitește niciodată ce a fost deja citit.

Semnătura nu se verifică la dumneavoastră

Receptorul dumneavoastră trebuie să recalculeze v1 = HMAC-SHA256(secret, t + "." + body) din corpul brut primit și să respingă orice t mai vechi de 5 min. Eșecurile clasice: corpul reserializat înainte de verificare (un JSON reformatat nu mai are aceiași octeți), un ceas care derivă dincolo de toleranță și o rotație ignorată — timp de 24 h antetul poartă câte un v1 pentru fiecare secret încă valid, și trebuie să acceptați dacă oricare se potrivește.

Remediul. Verificați pe octeții bruți, sincronizați-vă ceasul (NTP), testați-vă verificarea în timpul unei rotații. Fragmentele Node și Python din documentație fac exact asta — copiați-le în loc să le rescrieți.

Un eveniment sosește de două ori

Livrarea este at-least-once, în loturi de cel mult 100, în ordinea jurnalului; cursorul avansează doar la 2xx-ul dumneavoastră, lot cu lot. Un eșec după recepție, dar înainte ca cursorul să avanseze, provoacă o relivrare — acesta este contractul, nu un defect.

Remediul. seq-ul este cheia dumneavoastră de idempotență: procesați fiecare secvență exact o dată și răspundeți 2xx doar după persistare. Un 2xx timpuriu urmat de o cădere este singurul mod de a pierde un eveniment.

Jurnalul pare incomplet sau se repetă

depuisSeq este strict exclusiv: sunt returnate doar evenimentele cu un seq mai mare, sortate crescător, cel mult 500 pe pagină. Răspunsul returnează prochainSeq, de retransmis ca atare. O pagină mai scurtă decât limite înseamnă sfârșitul jurnalului.

Remediul. Persistați prochainSeq între rulări și nu îl recalculați niciodată singuri. Dublurile înseamnă că ați repornit de la un cursor prea vechi; golurile înseamnă că ați sărit o pagină eșuată fără să o rejucați.

Parametru în afara schemei

Un status necunoscut, o dispoziție în afara listei (planifie, traite, ecarte), o limite care nu este număr întreg: răspunsul numește câmpul vinovat, și nimic altceva — mesajele de eroare nu poartă niciodată conținut de dosar.

Remediul. Specificația OpenAPI este sursa: enumerările și limitele pe care le declară sunt cele pe care serverul le impune, fiindcă este servită chiar de el.

Câmp a cărui valoare este prea lungă: Cetățenia

Răspunsul numește câmpul vinovat, și nimic altceva — mesajele de eroare nu poartă niciodată conținut de dosar.

Remediul. Specificația OpenAPI este sursa: enumerările și limitele pe care le declară sunt cele pe care serverul le impune, fiindcă este servită chiar de el.

Scope insuficient (API-ul de resurse)

Endpoint-urile de resurse (/clients, /dossiers, documente, verificare în liste, alerte) cer un scope granular: clients:*, dossiers:*, pieces:*, criblage:* sau scope-ul dedicat alertes:qualifier. O cheie istorică lecture acordă toate scope-urile *:lecture, iar ecriture toate scope-urile *:ecriture — dar alertes:qualifier nu se moștenește niciodată: calificarea unei alerte este un act al responsabilului, delegat prin bifarea acestui scope la crearea cheii.

Remediul. Creați o cheie care poartă exact scope-urile de care are nevoie integrarea dumneavoastră — și doar pe acelea. Câmpul detail din răspuns numește scope-ul lipsă.

Resursă negăsită — sau a altui cabinet

Aceeași regulă ca la #cloisonnement, aplicată resurselor: un client, un dosar, un document sau o alertă care nu există sau care aparține altui cabinet primește același 404. API-ul nu deosebește niciodată cele două cazuri.

Remediul. Verificați identificatorul în listele cabinetului căruia îi aparține cheia. Un identificator nu circulă niciodată de la un cabinet la altul.

Antetul Idempotency-Key lipsește

Fiecare POST de creare sau de declanșare (client, dosar, document, verificare în liste, beneficiari reali) cere antetul Idempotency-Key: un șir stabil de cel mult 200 de caractere, unul per operațiune. Rejucarea aceleiași chei cu același corp returnează același răspuns, fără niciun efect — protecția dumneavoastră împotriva dublurilor la un incident de rețea.

Remediul. Generați cheia înainte de prima încercare (un UUID per operațiune de business) și refolosiți-o neschimbată la fiecare reîncercare a aceleiași operațiuni.

Cheie de idempotență refolosită cu un corp diferit

Acest Idempotency-Key a fost deja folosit pentru un corp diferit în ultimele 24 de ore. Cheia rejoacă un răspuns, nu îl suprascrie niciodată: refolosirea ei pentru o operațiune nouă este aproape întotdeauna semnul unei chei derivate dintr-un contor sau dintr-o dată trunchiată.

Remediul. O cheie nouă pentru fiecare operațiune nouă. Nu derivați niciodată cheia din date care se repetă de la o operațiune la alta.

O altă încercare cu această cheie este încă în curs

Două cereri cu aceeași Idempotency-Key au sosit împreună: prima se execută, a doua este refuzată înainte de orice efect. Acest refuz este ceea ce împiedică dublura. Cazul obișnuit: un proxy returnează 502 sau 504 în timp ce serverul încă lucrează, iar clientul dumneavoastră reia cererea. Antetul Retry-After spune după câte secunde să o reluați.

Remediul. Reluați aceeași cerere, așa cum este, cu aceeași cheie, după așteptarea anunțată: veți primi răspunsul primei încercări. Nu fabricați niciodată o cheie nouă pentru a „debloca” — ar crea exact dublura pe care cheia o evită.

Mediu de test: cota a fost atinsă

Un mediu de test are limite fixe: 200 de fișe de client, 50 de dosare și 40 de documente pe dosar. O creare sau o depunere care ar depăși una dintre ele este refuzată înainte de orice scriere, iar refuzul spune care anume: câmpurile ressource, quota și courant indică resursa, plafonul și numărul existent în momentul refuzului. Din două creări simultane pentru ultimul loc, trece doar una. Modificarea unei fișe sau a unui dosar existent nu consumă nimic.

Remediul. Aceste cote nu se negociază, iar reluarea cererii va aduce același refuz. Reinițializați mediul de test din spațiul dumneavoastră — pornește din nou de la datele demonstrative — sau încheiați un abonament: aceste cote se aplică doar mediilor de test.

Dosar sigilat: registrul este înghețat

Sigilarea îngheață lanțul de integritate al dosarului — aceasta este valoarea lui probatorie. Un dosar sigilat nu mai poate fi editat, nu mai primește documente și nu mai este re-verificat în liste prin acest canal. Rămâne posibilă doar calificarea alertelor: ea se scrie off-chain, capul sigilat nu se mișcă niciodată.

Remediul. Nimic de „corectat”: aceasta este imuabilitate deliberată. Dacă datele trebuie să se schimbe, este vorba de o nouă operațiune de vigilență în aplicație, nu de o mutație a dosarului sigilat.

Dosar închis: relația de afaceri s-a încheiat

Relația a fost închisă în aplicație: dosarul nu mai primește scrieri prin API — nici editare, nici document, nici verificare în liste, nici beneficiari reali. Citirile rămân deschise: un dosar închis se consultă și se exportă pe toată durata de păstrare.

Remediul. Redeschiderea relației este un gest uman, înregistrat, în aplicație; API-ul nu îl face în locul dumneavoastră. Dacă operațiunea este nouă, deschideți un dosar nou în loc să reînviați cel vechi.

Dosar purjat: datele au fost șterse

Termenul de păstrare a trecut și datele dosarului au fost șterse. Rămâne doar urma de audit, care atestă că un dosar a existat și că a fost purjat la data indicată; ea nu mai primește nicio scriere.

Remediul. Nimic de corectat și nimic de reluat: ștergerea este definitivă și voită. Un identificator de dosar purjat păstrat în sistemele dumneavoastră este un istoric, niciodată o țintă de scriere.

Format de document neacceptat

Documentele justificative acceptă PDF, JPG, JPEG, PNG și WEBP — aceleași formate ca aplicația. Verificarea se face pe extensia câmpului obligatoriu filename: un document fără un nume de fișier valid este refuzat, indiferent de conținut.

Remediul. Convertiți înainte de trimitere (o scanare TIFF sau HEIC se convertește în PDF sau JPEG) și trimiteți conținutul ca base64 standard în contenu, cu un type dintre codurile stabile a_doc_*.

Document de peste 6 MB

Limita se aplică fișierului decodat (6 MB), aceeași ca în aplicație și în portalul de colectare. Cum base64 adaugă o treime de supraîncărcare de codare, corpul cererii acceptă până la 9 MB.

Remediul. Comprimați documentul (un PDF scanat color la 300 dpi coboară aproape întotdeauna sub limită în tonuri de gri) în loc să îl fragmentați.

Sursă de verificare în liste indisponibilă

Niciuna dintre entitățile dosarului nu a putut fi verificată în liste: sursa (indexul de liste oficiale sau furnizorul) nu a răspuns. API-ul refuză să concluzioneze — un raport „curat” peste o sursă moartă ar fi cel mai rău fals negativ posibil. Eșecul este consemnat pe dosar (erreurSource). O pană parțială nu produce acest 502: răspunsul 200 păstrează potrivirile entităților care au răspuns și le numește pe cele eșuate în erreurSourceEntites.

Remediul. Rejucați același apel mai târziu, cu aceeași Idempotency-Key: doar răspunsurile de succes sunt memorate de idempotență — rejucarea după o eroare rulează o verificare reală.

Widgeturi încorporate neactivate pe această instanță

Mintul POST /api/v1/embed/jetons se bazează pe originile declarate pentru cabinetul dumneavoastră — această listă este cea care pilotează CSP-ul frame-ancestors al shell-ului încorporat. Acest 501 spune că instanța pe care ați apelat-o nu poartă acea stocare: suprafața de embed este acolo inertă prin construcție, și o spune în loc să emită un token pe care nicio origine nu l-ar putea afișa vreodată. A nu se confunda cu 400-ul returnat unui cabinet ale cărui origini nu sunt încă declarate.

Remediul. Acest 501 vorbește despre instanță, nu despre cererea dumneavoastră. Pe vigilae.org, administratorul cabinetului dumneavoastră declară el însuși originile, pe ecranul „Integrări și securitate” (caseta din secțiunea widgets spune unde); apoi rejucați același apel. Nimic de schimbat în codul dumneavoastră: cererea era bună, instanța nu era pregătită.

Suprafață indisponibilă pe această instalare

Două citiri de bază — GET /api/v1/dossiers/{id}/origine-fonds și GET /api/v1/dossiers/{id}/exigences — se sprijină pe depozite pe care nu le poartă orice instanță. Când unul lipsește, API-ul o spune în loc să servească o listă goală: „nimic de semnalat” și „nu s-a citit nimic” sunt fapte opuse, iar confundarea lor ar face ca un dosar pe care nu l-a deschis nimeni să treacă drept dosar fără rezerve. Acest 501 vorbește despre instanța apelată, niciodată despre cererea dumneavoastră sau despre dosar.

Remediul. Nu reluați apelul în buclă: nimic nu se va schimba câtă vreme instanța nu poartă acel depozit. Tratați acest cod ca „dată indisponibilă aici” și mai ales nu-l socotiți drept zero în tablourile de bord — așa devine o măsurătoare lipsă o cifră greșită. Pe vigilae.org ambele citiri sunt servite; pe o instalare dedicată, actualizarea depozitului revine operatorului dumneavoastră.