Ogni errore, spiegato a un indirizzo stabile.
Questa pagina è un riferimento operativo, non una vetrina. Ogni classe di errore dell'API Connect ha qui un'ancora permanente; le risposte di errore dell'API punteranno a questi indirizzi. Trovi la causa probabile e il rimedio — in quest'ordine. Torna alla documentazione per sviluppatori.
Chiave assente, malformata o sconosciuta
L'API autentica esclusivamente tramite l'intestazione Authorization: Bearer vgk_… — mai tramite un cookie di sessione. Una chiave revocata diventa sconosciuta nell'istante stesso della revoca.
Il rimedio. Verifica che l'intestazione parta davvero (a volte i proxy la rimuovono), che la chiave inizi con vgk_ e che non sia stata revocata dalla console dello studio. Poiché il segreto è mostrato solo alla creazione, una chiave persa si sostituisce, non si recupera.
Chiave scaduta
Ogni chiave scade un anno dopo la creazione — la data expire_le è visibile nella console dello studio fin dal primo giorno. Il 401 di scadenza è esplicito: dice che la chiave esisteva e non è più valida.
Il rimedio. Crea una nuova chiave, spostaci le tue chiamate, revoca la vecchia. Pianifica questa sostituzione nelle tue operazioni invece di scoprirla: la data è nota con un anno di anticipo.
Scope insufficiente
Le chiavi portano lecture (lettura, predefinito) e/o ecriture (scrittura). Qualificare un evento richiede ecriture; una chiave di sola lettura riceve un 403 qualunque sia la risorsa.
Il rimedio. Crea una chiave con lo scope necessario — e solo quello. Il privilegio minimo è una scelta deliberata: un'integrazione che si limita a leggere non ha motivo di detenere una chiave di scrittura.
Non trovata — o di un altro studio
Un 404 significa che la risorsa non esiste oppure appartiene a un altro studio. L'API non distingue mai i due casi: distinguerli rivelerebbe che cosa esiste altrove. La separazione è imposta a livello della banca dati, non solo nel codice applicativo.
Il rimedio. Controlla il seq rispetto al registro dello studio a cui appartiene la chiave (GET /api/v1/evenements). Se integri più studi, ogni studio ha le proprie chiavi: un seq non viaggia da uno studio all'altro.
Limite di richieste superato
60 richieste al minuto per chiave, come impostazione predefinita (modificabile per singola chiave). La risposta porta Retry-After e le intestazioni X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.
Il rimedio. Rispetta Retry-After — nessun nuovo tentativo immediato. Toccare il limite durante il polling è quasi sempre il segno di una ri-scansione completa: il cursore depuisSeq non rilegge mai ciò che è già stato letto.
La firma non si verifica dal tuo lato
Il tuo ricevitore deve ricalcolare v1 = HMAC-SHA256(secret, t + "." + body) dal corpo grezzo ricevuto e rifiutare ogni t più vecchio di 5 min. I guasti classici: il corpo ri-serializzato prima della verifica (un JSON riformattato non ha più gli stessi byte), un orologio che deriva oltre la tolleranza, e una rotazione ignorata — per 24 h l'intestazione porta un v1 per ogni segreto ancora valido, e devi accettare se almeno uno corrisponde.
Il rimedio. Verifica sui byte grezzi, sincronizza l'orologio (NTP), prova la tua verifica durante una rotazione. Gli snippet Node e Python nella documentazione fanno esattamente questo — copiali invece di riscriverli.
Un evento arriva due volte
La consegna è at-least-once, a lotti di al massimo 100, nell'ordine del registro; il cursore avanza solo al tuo 2xx, lotto per lotto. Un guasto dopo la ricezione ma prima dell'avanzamento del cursore provoca una riconsegna — è il contratto, non un difetto.
Il rimedio. Il seq è la tua chiave di idempotenza: elabora ogni sequenza esattamente una volta e rispondi 2xx solo dopo aver persistito. Un 2xx anticipato seguito da un crash è l'unico modo di perdere un evento.
Il registro sembra incompleto o si ripete
depuisSeq è strettamente esclusivo: sono restituiti solo gli eventi con seq superiore, in ordine crescente, al massimo 500 per pagina. La risposta restituisce prochainSeq, da ripassare tale e quale. Una pagina più corta di limite significa fine del registro.
Il rimedio. Persisti prochainSeq tra un'esecuzione e l'altra e non ricalcolarlo mai da solo. I duplicati significano che sei ripartito da un cursore troppo vecchio; i buchi, che hai saltato una pagina fallita senza ritentarla.
Parametro fuori dallo schema
Uno stato sconosciuto, una disposizione fuori dall'elenco (planifie, traite, ecarte), un limite non intero: la risposta nomina il campo in errore, e nient'altro — i messaggi di errore non trasportano mai contenuti di pratica.
Il rimedio. La specifica OpenAPI è la fonte: le enumerazioni e i limiti che dichiara sono quelli che il server applica, dato che è lui a servirla.
Scope insufficiente (API delle risorse)
Gli endpoint delle risorse (/clients, /dossiers, documenti, screening, allerte) richiedono uno scope granulare: clients:*, dossiers:*, pieces:*, criblage:* o lo scope dedicato alertes:qualifier. Una chiave storica lecture concede tutti gli scope *:lecture e una ecriture tutti gli *:ecriture — ma alertes:qualifier non si eredita mai: qualificare un'allerta è un atto del responsabile AML/CFT, delegato spuntando quello scope alla creazione della chiave.
Il rimedio. Crea una chiave con esattamente gli scope di cui la tua integrazione ha bisogno — e solo quelli. Il detail della risposta nomina lo scope mancante.
Risorsa non trovata — o di un altro studio
Stessa regola di #cloisonnement, applicata alle risorse: un cliente, una pratica, un documento o un'allerta che non esiste oppure che appartiene a un altro studio riceve lo stesso 404. L'API non distingue mai i due casi.
Il rimedio. Controlla l'identificativo rispetto agli elenchi dello studio a cui appartiene la chiave. Un identificativo non viaggia mai da uno studio all'altro.
Intestazione Idempotency-Key assente
Ogni POST di creazione o di attivazione (cliente, pratica, documento, screening, titolari effettivi) richiede l'intestazione Idempotency-Key: una stringa stabile di al massimo 200 caratteri, una per operazione. Ripetere la stessa chiave con lo stesso corpo restituisce la stessa risposta, senza alcun effetto — la tua protezione contro i duplicati in caso di incidente di rete.
Il rimedio. Genera la chiave prima del primo tentativo (un UUID per ciascuna operazione) e riusala identica a ogni nuovo tentativo della stessa operazione.
Chiave di idempotenza riutilizzata con un corpo diverso
Questa Idempotency-Key è già stata usata per un corpo diverso nelle ultime 24 ore. La chiave restituisce di nuovo una risposta, non la sovrascrive mai: riutilizzarla per una nuova operazione è quasi sempre il segno di una chiave derivata da un contatore o da una data troncata.
Il rimedio. Una chiave nuova per ogni nuova operazione. Non derivare mai la chiave da dati che si ripetono da un'operazione all'altra.
Pratica sigillata: il registro è congelato
La sigillatura congela la catena di integrità della pratica — è il suo valore probatorio. Una pratica sigillata non si può più modificare, non riceve più documenti e non viene più sottoposta a ri-screening da questo canale. Resta possibile solo la qualificazione delle allerte: viene scritta off-chain, la testa sigillata non si muove mai.
Il rimedio. Niente da "correggere": è immutabilità voluta. Se i dati devono cambiare, si tratta di una nuova operazione di adeguata verifica nell'applicazione, non di una mutazione della pratica sigillata.
Formato del documento non accettato
I documenti giustificativi accettano PDF, JPG, JPEG, PNG e WEBP — gli stessi formati dell'applicazione. Il controllo è sull'estensione del filename obbligatorio: un documento senza nome di file valido è rifiutato, qualunque sia il contenuto.
Il rimedio. Converti prima di inviare (una scansione TIFF o HEIC si converte in PDF o JPEG) e invia il contenuto in base64 standard in contenu, con un type tra i codici stabili a_doc_*.
Documento oltre i 6 MB
Il limite si applica al file decodificato (6 MB), lo stesso dell'applicazione e del portale di raccolta. Poiché il base64 aggiunge un terzo di sovraccarico di codifica, il corpo della richiesta accetta fino a 9 MB.
Il rimedio. Comprimi il documento (un PDF scansionato a colori a 300 dpi scende quasi sempre sotto il limite in scala di grigi) invece di dividerlo.
Fonte di screening non disponibile
Nessuna delle entità della pratica ha potuto essere controllata rispetto alle liste: la fonte (indice delle liste ufficiali o fornitore) non ha risposto. L'API si rifiuta di concludere — un rapporto "pulito" sopra una fonte morta sarebbe il peggior falso negativo possibile. Il guasto è registrato sulla pratica (erreurSource). Un'interruzione parziale non produce questo 502: la risposta 200 conserva le corrispondenze delle entità che hanno risposto e nomina quelle fallite in erreurSourceEntites.
Il rimedio. Ritenta la stessa chiamata più tardi, con la stessa Idempotency-Key: l'idempotenza memorizza solo le risposte di successo — ritentare dopo un errore esegue uno screening reale.
Questa pagina evolverà con l'API; le ancore esistenti, però, non cambiano mai indirizzo — puoi conservarle nei tuoi log operativi.