Fiecare eroare, explicată la o adresă stabilă.
Această pagină este o referință operațională, nu un discurs comercial. Fiecare clasă de erori a API-ului Connect are aici o ancoră permanentă; răspunsurile de eroare ale API-ului vor trimite către aceste adrese. Primiți cauza probabilă și remediul — în această ordine. Înapoi la documentația pentru dezvoltatori.
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.
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ă.
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ă.
Remediul. Creați o cheie nouă, mutați apelurile pe ea, revocați-o pe cea veche. Planificați această înlocuire în operațiunile dumneavoastră în loc să o descoperiți: data este cunoscută cu un an înainte.
Scope insuficient
Cheile poartă lecture (citire, implicit) și/sau ecriture (scriere). Calificarea unui eveniment necesită ecriture; o cheie doar de citire primește un 403 indiferent de resursă.
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.
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.
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.
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.
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.
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ă.
Această pagină va evolua odată cu API-ul; ancorele existente, în schimb, nu își schimbă niciodată adresa — le puteți păstra în jurnalele dumneavoastră operaționale.