Ogni errore, spiegato a un indirizzo stabile.

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.

Lo stesso 401 riporta "motif": "fin_option_api" quando la chiave è stata fermata perché l'API non fa più parte dell'abbonamento dello studio. La data di questo arresto è stata indicata in un'e-mail agli amministratori dello studio o, in mancanza, all'indirizzo di fatturazione dello studio, poi annunciata nell'intestazione Sunset di ogni risposta a una chiamata accettata (calendario in #cle-expiree). Senza motivo, può anche derivare da un abbonamento sospeso: la sospensione interrompe le chiavi all'istante.

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. Con "motif": "fin_option_api", né l'intestazione né la chiave sono in causa: l'amministratore dello studio ci scrive a contact@vigilae.org perché l'API rientri nell'abbonamento, e la stessa chiave torna a essere accettata appena fatto, fino alla sua scadenza.

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.

Una chiave API può anche smettere di essere accettata prima di questa data, quando l'API non fa più parte dell'abbonamento dello studio. L'arresto cade allora almeno 30 giorni dopo una prima e-mail, alla data indicata da una seconda e-mail, inviata almeno 7 giorni prima; entrambe vanno agli amministratori dello studio o, in mancanza, all'indirizzo di fatturazione dello studio. Una volta fissata, questa data si legge nella console dello studio (campo coupure_le di GET /connect/cles), e ogni risposta a una chiamata accettata la annuncia nell'intestazione Sunset finché non arriva. Dopo questa data, la chiamata riceve il 401 descritto in #authentification, con "motif": "fin_option_api"; se l'API rientra nell'abbonamento, la chiave torna a essere accettata, fino alla sua scadenza.

Il rimedio. Crea una nuova chiave, spostaci le tue chiamate, revoca la vecchia. Per una chiave API serve però che l'API faccia ancora parte dell'abbonamento dello studio: senza di essa, la console rifiuta di crearne una. Pianifica questa sostituzione nelle tue operazioni invece di scoprirla.

Scope insufficiente

Le chiavi portano gli scope selezionati alla loro creazione: quelli generali lecture (lettura, predefinito) e ecriture (scrittura), oppure quelli fini per risorsa (clients:lecture, pieces:ecriture, origine-fonds:lecture, journal:lecture…).

L'ereditarietà segue il suffisso, in un solo senso: lecture copre ogni *:lecture, ecriture ogni *:ecriture — mai il contrario; uno scope fine apre soltanto sé stesso.

Sei scope escono da questa coppia e non si ereditano da nessuna chiave generale: alertes:qualifier, embed:emettre, adversemedia:consulter, conformite:consulter, dispositif:consulter, integrite:consulter. Qualificare un evento, emettere un token di embed, leggere la stampa sfavorevole di un fascicolo o un punteggio di tenuta non discende mai da un diritto di lettura generale: ciascuno si seleziona a parte.

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, e una chiave ampia non rimedierà mai a uno scope non delegato in modo esplicito.

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.

Questo account esiste già

Un POST /scim/v2/Users su un userName già fornito per questo studio risponde 409 con scimType: uniqueness. L'unicità è retta da un vincolo di database, non da una cache: due creazioni simultanee non possono produrre due account.

Il rimedio. Tratta il 409 come un successo idempotente, non come un errore: rileggi l'account con ?filter=userName eq "…" e prosegui con l'identificativo restituito. Un connettore che ritenta in ciclo su un 409 non creerà mai nulla di più.

Questo account è fuori dalla portata della directory

Una directory non può né retrocedere né disattivare un account che porta poteri di amministrazione dello studio: la richiesta è respinta con scimType: mutability e registrata. Senza questo limite, un connettore che adotta l'indirizzo del responsabile della conformità chiuderebbe lo studio proprio a chi ne risponde.

Il rimedio. Togli questa persona dal perimetro sincronizzato, oppure cambiane il ruolo da Vigilae. Il rifiuto riguarda solo questo account: il resto del lotto viene applicato normalmente.

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.

Campo il cui valore è troppo lungo: Nazionalità

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.

Un altro tentativo con questa chiave è ancora in corso

Due richieste con la stessa Idempotency-Key sono arrivate insieme: la prima viene eseguita, la seconda è rifiutata prima di ogni effetto. È questo rifiuto a impedire il duplicato. Il caso frequente: un proxy restituisce 502 o 504 mentre il server sta ancora lavorando, e il tuo client ripete la richiesta. L'intestazione Retry-After indica dopo quanti secondi ripeterla.

Il rimedio. Ripeti la stessa richiesta, così com'è, con la stessa chiave, dopo l'attesa indicata: riceverai la risposta del primo tentativo. Non fabbricare mai una chiave nuova per «sbloccare»: creerebbe proprio il duplicato che la chiave evita.

Ambiente di test: quota raggiunta

Un ambiente di test ha limiti fissi: 200 schede cliente, 50 pratiche e 40 documenti per pratica. Una creazione o un deposito che supererebbe uno di questi limiti viene rifiutato prima di qualsiasi scrittura, e il rifiuto indica quale: i campi ressource, quota e courant riportano la risorsa, il tetto e il conteggio al momento del rifiuto. Se due creazioni simultanee si contendono l'ultimo posto, ne passa una sola. Modificare una scheda o una pratica già esistente non consuma nulla.

Il rimedio. Queste quote non sono negoziabili, e ripetere la richiesta restituirà lo stesso rifiuto. Reimposta l'ambiente di test dalla tua area — riparte dai dati demo — oppure sottoscrivi un abbonamento: queste quote valgono solo per gli ambienti di test.

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.

Pratica chiusa: il rapporto d'affari è terminato

Il rapporto è stato chiuso nell'applicazione: la pratica non riceve più scritture dall'API — né modifica, né documento, né screening, né titolari effettivi. Le letture restano aperte: una pratica chiusa si consulta e si esporta per tutta la durata di conservazione.

Il rimedio. Riaprire il rapporto è un gesto umano e tracciato, nell'applicazione; l'API non lo fa al tuo posto. Se l'operazione è nuova, apri una pratica nuova invece di rianimare quella vecchia.

Pratica cancellata: i dati sono stati eliminati

Il termine di conservazione è scaduto e i dati della pratica sono stati eliminati. Resta solo la traccia di audit, che attesta che una pratica è esistita e che è stata cancellata alla data indicata; non riceve più alcuna scrittura.

Il rimedio. Niente da correggere e niente da ripetere: la cancellazione è definitiva e voluta. Un identificativo di pratica cancellata conservato nei tuoi sistemi è uno storico, mai un bersaglio di scrittura.

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.

Widget incorporati non abilitati su questa istanza

Il mint POST /api/v1/embed/jetons si basa sulle origini dichiarate per il tuo studio — è quella lista a pilotare la CSP frame-ancestors dello shell incorporato. Questo 501 dice che l'istanza chiamata non porta quello storage: la superficie di embed lì è inerte per costruzione, e lo dice invece di emettere un token che nessuna origine potrebbe mai mostrare. Da non confondere con il 400 restituito a uno studio le cui origini non sono ancora dichiarate.

Il rimedio. Questo 501 parla dell'istanza, non della tua richiesta. Su vigilae.org, l'amministratore del tuo studio dichiara lui stesso le origini, nella schermata «Integrazioni e sicurezza» (il riquadro nella sezione widget dice dove); poi ripeti la stessa chiamata. Niente da correggere nel tuo codice: la richiesta era corretta, l'istanza non era pronta.

Superficie non disponibile su questa istanza

Due letture di base — GET /api/v1/dossiers/{id}/origine-fonds e GET /api/v1/dossiers/{id}/exigences — si appoggiano ad archivi che non tutte le istanze possiedono. Quando ne manca uno, l'API lo dice invece di servire una lista vuota: «nulla da segnalare» e «nulla è stato letto» sono fatti opposti, e confonderli farebbe passare un fascicolo che nessuno ha aperto per un fascicolo senza rilievi. Questo 501 parla dell'istanza chiamata, mai della tua richiesta né del fascicolo.

Il rimedio. Non riprovare in ciclo: nulla cambierà finché l'istanza non possiederà quell'archivio. Tratta questo codice come «dato non disponibile qui» e soprattutto non contarlo come uno zero nei tuoi cruscotti — è così che una misura assente diventa una cifra sbagliata. Su vigilae.org entrambe le letture sono servite; su un deployment dedicato, l'aggiornamento dell'archivio spetta al tuo gestore.