Jeder Fehler, erklärt unter einer stabilen Adresse.
Diese Seite ist eine Betriebsreferenz, kein Pitch. Jede Fehlerklasse der Connect-API hat hier einen permanenten Anker; die Fehlerantworten der API werden auf diese Adressen verweisen. Sie bekommen die wahrscheinliche Ursache und die Abhilfe — in dieser Reihenfolge. Zurück zur Entwicklerdokumentation.
Schlüssel fehlt, ist fehlerhaft oder unbekannt
Die API authentifiziert ausschließlich über den Header Authorization: Bearer vgk_… — nie über ein Session-Cookie. Ein widerrufener Schlüssel wird in dem Moment unbekannt, in dem er widerrufen wird.
Derselbe 401 trägt "motif": "fin_option_api", wenn der Schlüssel gestoppt wurde, weil die API nicht mehr Teil des Abonnements der Kanzlei ist. Das Datum dieses Stopps wurde in einer E-Mail an die Administratoren der Kanzlei oder, falls es keine gibt, an die Rechnungsadresse der Kanzlei genannt und danach im Header Sunset jeder Antwort auf einen angenommenen Aufruf angekündigt (Zeitplan unter #cle-expiree). Ohne Motiv kann er auch von einem ausgesetzten Abonnement stammen: Die Aussetzung sperrt die Schlüssel sofort.
Die Abhilfe. Prüfen Sie, dass der Header tatsächlich abgeht (Proxys streichen ihn manchmal), dass der Schlüssel mit vgk_ beginnt und dass er nicht in der Konsole der Kanzlei widerrufen wurde. Da das Geheimnis nur bei der Erstellung angezeigt wird, wird ein verlorener Schlüssel ersetzt, nicht wiederhergestellt. Bei "motif": "fin_option_api" liegt der Fehler weder am Header noch am Schlüssel: Ein Administrator der Kanzlei schreibt uns an contact@vigilae.org, damit die API wieder ins Abonnement aufgenommen wird, und derselbe Schlüssel wird wieder angenommen, sobald das geschehen ist, bis zu seinem eigenen Ablaufdatum.
Abgelaufener Schlüssel
Jeder Schlüssel läuft ein Jahr nach der Erstellung ab — das Datum expire_le ist von Tag eins an in der Konsole der Kanzlei sichtbar. Der Ablauf-401 ist explizit: Er sagt, dass der Schlüssel existierte und nicht mehr gültig ist.
Ein API-Schlüssel kann auch vor diesem Datum nicht mehr angenommen werden, wenn die API nicht mehr Teil des Abonnements der Kanzlei ist. Der Stopp erfolgt dann mindestens 30 Tage nach einer ersten E-Mail, an dem Datum, das eine zweite E-Mail nennt, die mindestens 7 Tage vorher verschickt wird; beide gehen an die Administratoren der Kanzlei oder, falls es keine gibt, an die Rechnungsadresse der Kanzlei. Sobald es feststeht, ist dieses Datum in der Konsole der Kanzlei sichtbar (Feld coupure_le von GET /connect/cles), und jede Antwort auf einen angenommenen Aufruf kündigt es im Header Sunset an, bis es erreicht ist. Danach erhält der Aufruf den 401 aus #authentification, mit "motif": "fin_option_api"; ist die API wieder Teil des Abonnements, wird der Schlüssel wieder angenommen, bis zu seinem eigenen Ablaufdatum.
Die Abhilfe. Erstellen Sie einen neuen Schlüssel, stellen Sie Ihre Aufrufe um, widerrufen Sie den alten. Für einen API-Schlüssel muss die API dazu noch Teil des Abonnements der Kanzlei sein: Ohne sie lehnt die Konsole das Erstellen eines Schlüssels ab. Planen Sie diesen Wechsel in Ihrem Betrieb ein, statt ihn zu entdecken.
Unzureichender Scope
Schlüssel tragen die bei ihrer Erstellung angekreuzten Scopes: die allgemeinen lecture (Lesen, der Standard) und ecriture (Schreiben) oder feingranulare je Ressource (clients:lecture, pieces:ecriture, origine-fonds:lecture, journal:lecture…).
Die Vererbung folgt dem Suffix, und nur in eine Richtung: lecture deckt jedes *:lecture ab, ecriture jedes *:ecriture — umgekehrt gilt das nie; ein feingranularer Scope öffnet nur sich selbst.
Sechs Scopes fallen aus diesem Paar heraus und werden von keinem allgemeinen Schlüssel geerbt: alertes:qualifier, embed:emettre, adversemedia:consulter, conformite:consulter, dispositif:consulter, integrite:consulter. Ein Ereignis qualifizieren, ein Embed-Token ausstellen, die nachteilige Presse zu einem Dossier oder eine Note zur Aktenführung lesen — nichts davon folgt aus einem allgemeinen Leserecht: Jeder dieser Scopes wird einzeln angekreuzt.
Die Abhilfe. Erstellen Sie einen Schlüssel mit dem benötigten Scope — und nur mit diesem. Die geringste Berechtigung ist Absicht: Eine Integration, die nur liest, hat keinen Grund, einen Schreibschlüssel zu halten, und ein weit gefasster Schlüssel ersetzt niemals einen Scope, der nicht ausdrücklich delegiert wurde.
Nicht gefunden — oder von einer anderen Kanzlei
Ein 404 bedeutet: Die Ressource existiert nicht, oder sie gehört einer anderen Kanzlei. Die API unterscheidet die beiden Fälle nie: Zu unterscheiden hieße zu verraten, was anderswo existiert. Die Trennung wird auf Datenbankebene erzwungen, nicht nur im Anwendungscode.
Die Abhilfe. Prüfen Sie die seq gegen das Journal der Kanzlei, zu der der Schlüssel gehört (GET /api/v1/evenements). Wenn Sie mehrere Kanzleien integrieren, hat jede Kanzlei ihre eigenen Schlüssel: Eine seq wandert nicht zwischen Kanzleien.
Dieses Konto besteht bereits
Ein POST /scim/v2/Users auf einen für diese Kanzlei bereits bereitgestellten userName antwortet mit 409 und scimType: uniqueness. Die Eindeutigkeit hält eine Datenbankbedingung, kein Zwischenspeicher: Zwei gleichzeitige Anlagen können nicht zwei Konten erzeugen.
Die Abhilfe. Behandeln Sie den 409 als idempotenten Erfolg, nicht als Fehler: Lesen Sie das Konto über ?filter=userName eq "…" zurück und arbeiten Sie mit der gelieferten Kennung weiter. Ein Konnektor, der bei einem 409 in Schleife wiederholt, erzeugt niemals mehr.
Dieses Konto liegt außerhalb der Reichweite des Verzeichnisses
Ein Verzeichnis kann ein Konto mit Verwaltungsbefugnissen der Kanzlei weder herabstufen noch deaktivieren: Die Anfrage wird mit scimType: mutability abgelehnt und protokolliert. Ohne diese Grenze würde ein Konnektor, der die Adresse des Geldwäschebeauftragten übernimmt, die Kanzlei genau für den verschließen, der für sie einsteht.
Die Abhilfe. Nehmen Sie diese Person aus dem synchronisierten Bereich, oder ändern Sie ihre Rolle in Vigilae. Die Ablehnung betrifft nur dieses Konto: Der Rest des Stapels wird normal angewandt.
Rate überschritten
60 Anfragen pro Minute je Schlüssel, standardmäßig (je Schlüssel anpassbar). Die Antwort trägt Retry-After und die Header X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.
Die Abhilfe. Respektieren Sie Retry-After — kein sofortiger Retry. Beim Polling ans Limit zu stoßen ist fast immer das Zeichen eines vollständigen Re-Scans: Der Cursor depuisSeq liest nie erneut, was schon gelesen wurde.
Die Signaturprüfung schlägt auf Ihrer Seite fehl
Ihr Empfänger muss v1 = HMAC-SHA256(secret, t + "." + body) aus dem rohen empfangenen Body neu berechnen und jedes t verwerfen, das älter als 5 min ist. Die Klassiker: der vor der Prüfung neu serialisierte Body (neu formatiertes JSON hat nicht mehr dieselben Bytes), eine Uhr, die über die Toleranz hinaus driftet, und eine ignorierte Rotation — 24 h lang trägt der Header ein v1 je noch gültigem Secret, und Sie müssen akzeptieren, wenn eines passt.
Die Abhilfe. Prüfen Sie gegen die rohen Bytes, synchronisieren Sie Ihre Uhr (NTP), testen Sie Ihre Prüfung während einer Rotation. Die Node- und Python-Snippets in der Dokumentation tun genau das — kopieren Sie sie, statt sie neu zu schreiben.
Ein Ereignis kommt zweimal an
Die Zustellung ist at-least-once, in Batches von höchstens 100, in Journalreihenfolge; der Cursor rückt nur auf Ihr 2xx vor, Batch für Batch. Ein Fehler nach dem Empfang, aber bevor der Cursor vorrückt, führt zu einer erneuten Zustellung — das ist der Vertrag, kein Defekt.
Die Abhilfe. Die seq ist Ihr Idempotenzschlüssel: Verarbeiten Sie jede Sequenz genau einmal, und antworten Sie erst nach dem Persistieren mit 2xx. Ein zu frühes 2xx, gefolgt von einem Absturz, ist der einzige Weg, ein Ereignis zu verlieren.
Das Journal wirkt unvollständig oder wiederholt sich
depuisSeq ist strikt exklusiv: Nur Ereignisse mit höherer seq werden zurückgegeben, aufsteigend sortiert, höchstens 500 je Seite. Die Antwort liefert prochainSeq, unverändert zurückzugeben. Eine Seite kürzer als limite bedeutet das Ende des Journals.
Die Abhilfe. Persistieren Sie prochainSeq zwischen den Läufen und berechnen Sie es nie selbst neu. Duplikate heißen: Sie sind von einem zu alten Cursor neu gestartet; Lücken heißen: Sie haben eine fehlgeschlagene Seite übersprungen, ohne sie zu wiederholen.
Parameter außerhalb des Schemas
Ein unbekannter Status, eine Disposition außerhalb der Liste (planifie, traite, ecarte), eine nicht ganzzahlige limite: Die Antwort nennt das betroffene Feld, und sonst nichts — Fehlermeldungen tragen nie Dossierinhalt.
Die Abhilfe. Die OpenAPI-Spezifikation ist die Quelle: Die Enumerationen und Grenzen, die sie deklariert, sind die, die der Server erzwingt — denn er liefert sie selbst aus.
Feldwert zu lang: Staatsangehörigkeit
Die Antwort nennt das betroffene Feld, und sonst nichts — Fehlermeldungen tragen nie Dossierinhalt.
Die Abhilfe. Die OpenAPI-Spezifikation ist die Quelle: Die Enumerationen und Grenzen, die sie deklariert, sind die, die der Server erzwingt — denn er liefert sie selbst aus.
Unzureichender Scope (Ressourcen-API)
Die Ressourcen-Endpunkte (/clients, /dossiers, Unterlagen, Screening, Alerts) erfordern einen feingranularen Scope: clients:*, dossiers:*, pieces:*, criblage:* oder den eigenen Scope alertes:qualifier. Ein Legacy-Schlüssel lecture gewährt jeden *:lecture-Scope und ecriture jeden *:ecriture-Scope — alertes:qualifier wird jedoch nie vererbt: Das Qualifizieren eines Alerts ist der Akt eines Verantwortlichen, delegiert durch das Ankreuzen dieses Scopes bei der Erstellung des Schlüssels.
Die Abhilfe. Erstellen Sie einen Schlüssel mit genau den Scopes, die Ihre Integration braucht — und nur mit diesen. Das Feld detail der Antwort nennt den fehlenden Scope.
Ressource nicht gefunden — oder von einer anderen Kanzlei
Dieselbe Regel wie #cloisonnement, angewandt auf Ressourcen: Ein Kunde, ein Dossier, eine Unterlage oder ein Alert, der nicht existiert oder einer anderen Kanzlei gehört, erhält denselben 404. Die API unterscheidet die beiden Fälle nie.
Die Abhilfe. Prüfen Sie den Identifikator gegen die Auflistungen der Kanzlei, zu der der Schlüssel gehört. Ein Identifikator wandert nie von einer Kanzlei zur anderen.
Header Idempotency-Key fehlt
Jeder erzeugende oder auslösende POST (Kunde, Dossier, Unterlage, Screening, wirtschaftlich Berechtigte) erfordert den Header Idempotency-Key: eine stabile Zeichenkette von höchstens 200 Zeichen, eine je Vorgang. Das Wiederholen desselben Schlüssels mit demselben Body liefert dieselbe Antwort, ohne Wirkung — Ihr Schutz gegen Duplikate bei einem Netzwerkzwischenfall.
Die Abhilfe. Erzeugen Sie den Schlüssel vor dem ersten Versuch (eine UUID je Geschäftsvorgang) und verwenden Sie ihn unverändert für jeden Retry desselben Vorgangs wieder.
Idempotenzschlüssel mit anderem Body wiederverwendet
Dieser Idempotency-Key wurde innerhalb der letzten 24 Stunden bereits für einen anderen Body verwendet. Der Schlüssel spielt eine Antwort erneut ab, er überschreibt nie eine: Ihn für einen neuen Vorgang wiederzuverwenden ist fast immer das Zeichen eines Schlüssels, der aus einem Zähler oder einem gekürzten Datum abgeleitet ist.
Die Abhilfe. Ein neuer Schlüssel für jeden neuen Vorgang. Leiten Sie den Schlüssel nie aus Daten ab, die sich über Vorgänge hinweg wiederholen.
Ein weiterer Versuch mit diesem Schlüssel läuft noch
Zwei Anfragen mit demselben Idempotency-Key sind gleichzeitig eingetroffen: Die erste wird ausgeführt, die zweite vor jeder Wirkung abgewiesen. Genau diese Abweisung verhindert das Duplikat. Der übliche Fall: Ein Proxy liefert 502 oder 504, während der Server noch arbeitet, und Ihr Client wiederholt die Anfrage. Der Header Retry-After nennt die Sekunden, nach denen zu wiederholen ist.
Die Abhilfe. Wiederholen Sie dieselbe Anfrage unverändert, mit demselben Schlüssel, nach der angegebenen Wartezeit: Sie erhalten die Antwort des ersten Versuchs. Erzeugen Sie niemals einen neuen Schlüssel, um „freizugeben“ — das würde genau das Duplikat schaffen, das der Schlüssel verhindert.
Testumgebung: Kontingent erreicht
Eine Testumgebung hat feste Grenzen: 200 Kundendatensätze, 50 Dossiers und 40 Unterlagen pro Dossier. Eine Anlage oder ein Upload, der eine davon überschreiten würde, wird vor jedem Schreibvorgang abgewiesen, und die Abweisung sagt, welche: Die Felder ressource, quota und courant nennen die Ressource, die Obergrenze und den Stand zum Zeitpunkt der Abweisung. Konkurrieren zwei gleichzeitige Anlagen um den letzten Platz, kommt nur eine durch. Einen bestehenden Kundendatensatz oder ein bestehendes Dossier zu bearbeiten, verbraucht nichts vom Kontingent.
Die Abhilfe. Diese Kontingente sind nicht verhandelbar, und eine wiederholte Anfrage erhält dieselbe Abweisung. Setzen Sie die Testumgebung in Ihrem Konto zurück — sie beginnt wieder mit den Demonstrationsdaten — oder schließen Sie ein Abonnement ab: Diese Kontingente gelten nur für Testumgebungen.
Versiegeltes Dossier: das Register ist eingefroren
Die Versiegelung friert die Integritätskette des Dossiers ein — das ist ihr Beweiswert. Ein versiegeltes Dossier lässt sich nicht mehr bearbeiten, nimmt keine Unterlagen mehr an und durchläuft über diesen Kanal kein erneutes Screening mehr. Nur die Qualifizierung von Alerts bleibt möglich: Sie wird off-chain geschrieben, der versiegelte Kopf bewegt sich nie.
Die Abhilfe. Nichts zu „korrigieren“: Das ist gewollte Unveränderlichkeit. Wenn Daten sich ändern müssen, ist das ein neuer Sorgfaltsvorgang in der Anwendung, keine Mutation des versiegelten Dossiers.
Abgeschlossenes Dossier: die Geschäftsbeziehung ist beendet
Die Beziehung wurde in der Anwendung beendet: Das Dossier nimmt über die API keine Schreibvorgänge mehr an — weder Bearbeitung noch Unterlage, noch Screening, noch wirtschaftlich Berechtigte. Lesezugriffe bleiben offen: Ein abgeschlossenes Dossier lässt sich während der gesamten Aufbewahrungsfrist einsehen und exportieren.
Die Abhilfe. Die Beziehung wieder aufzunehmen ist eine menschliche, protokollierte Handlung in der Anwendung; die API tut es nicht an Ihrer Stelle. Ist der Vorgang neu, legen Sie ein neues Dossier an, statt das alte zu reaktivieren.
Gelöschtes Dossier: die Daten sind entfernt
Die Aufbewahrungsfrist ist abgelaufen und die Daten des Dossiers wurden gelöscht. Es bleibt nur die Audit-Spur, die bezeugt, dass ein Dossier bestand und zum genannten Datum gelöscht wurde; sie nimmt keinen Schreibvorgang mehr an.
Die Abhilfe. Nichts zu korrigieren und nichts zu wiederholen: Die Löschung ist endgültig und gewollt. Eine in Ihren Systemen aufbewahrte Kennung eines gelöschten Dossiers ist Historie, niemals ein Ziel für Schreibvorgänge.
Dokumentformat nicht akzeptiert
Die Unterlagen akzeptieren PDF, JPG, JPEG, PNG und WEBP — dieselben Formate wie die Anwendung. Geprüft wird die Endung des verpflichtenden filename: Eine Unterlage ohne gültigen Dateinamen wird abgelehnt, gleich welchen Inhalts.
Die Abhilfe. Konvertieren Sie vor dem Senden (ein TIFF- oder HEIC-Scan lässt sich nach PDF oder JPEG wandeln) und senden Sie den Inhalt als Standard-Base64 in contenu, mit einem type aus den stabilen a_doc_*-Codes.
Unterlage über 6 MB
Die Grenze gilt für die dekodierte Datei (6 MB), dieselbe wie in der Anwendung und im Erfassungsportal. Da Base64 ein Drittel Kodierungsaufwand hinzufügt, akzeptiert der Request-Body bis zu 9 MB.
Die Abhilfe. Komprimieren Sie die Unterlage (ein in Farbe mit 300 dpi gescanntes PDF fällt in Graustufen fast immer unter die Grenze), statt sie zu zerteilen.
Screening-Quelle nicht verfügbar
Keine der Entitäten des Dossiers konnte gegen die Listen abgeglichen werden: Die Quelle (Index der offiziellen Listen oder Anbieter) hat nicht geantwortet. Die API weigert sich, ein Fazit zu ziehen — ein „sauberer“ Bericht auf einer toten Quelle wäre das schlimmstmögliche falsche Negativ. Der Ausfall wird am Dossier vermerkt (erreurSource). Ein teilweiser Ausfall erzeugt diesen 502 nicht: Die 200-Antwort behält die Treffer der Entitäten, die geantwortet haben, und nennt die fehlgeschlagenen in erreurSourceEntites.
Die Abhilfe. Wiederholen Sie denselben Aufruf später, mit demselben Idempotency-Key: Nur Erfolgsantworten werden von der Idempotenz gespeichert — ein erneuter Versuch nach einem Fehler führt ein echtes Screening aus.
Eingebettete Widgets auf dieser Instanz nicht aktiviert
Der Mint POST /api/v1/embed/jetons stützt sich auf die für Ihre Kanzlei deklarierten Origins — diese Liste steuert die frame-ancestors-CSP der eingebetteten Shell. Dieser 501 sagt, dass die aufgerufene Instanz diesen Speicher nicht trägt: Die Embed-Oberfläche ist dort konstruktionsbedingt inaktiv, und sie sagt das, statt einen Token auszustellen, den keine Origin je anzeigen könnte. Nicht zu verwechseln mit dem 400, den eine Kanzlei erhält, deren Origins noch nicht deklariert sind.
Die Abhilfe. Dieser 501 betrifft die Instanz, nicht Ihre Anfrage. Auf vigilae.org deklariert der Administrator Ihrer Kanzlei die Origins selbst, auf dem Bildschirm „Integrationen & Sicherheit“ (der Kasten im Abschnitt Widgets sagt, wo); wiederholen Sie danach denselben Aufruf. Nichts an Ihrem Code zu ändern: Die Anfrage war in Ordnung, die Instanz war nicht bereit.
Oberfläche auf dieser Instanz nicht verfügbar
Zwei Basislesungen — GET /api/v1/dossiers/{id}/origine-fonds und GET /api/v1/dossiers/{id}/exigences — stützen sich auf Speicher, die nicht jede Instanz trägt. Fehlt einer, sagt die API das, statt eine leere Liste zu liefern: „nichts zu vermelden“ und „nichts wurde gelesen“ sind gegensätzliche Tatsachen, und sie zu verwechseln ließe ein nie eingesehenes Dossier als Dossier ohne Beanstandung erscheinen. Dieser 501 betrifft die aufgerufene Instanz, nie Ihre Anfrage und nie das Dossier.
Die Abhilfe. Wiederholen Sie den Aufruf nicht in Schleife: Es ändert sich nichts, solange die Instanz diesen Speicher nicht trägt. Behandeln Sie den Code als „Daten hier nicht verfügbar“ und zählen Sie ihn vor allem nicht als Null in Ihren Dashboards — so wird aus einer fehlenden Messung eine falsche Zahl. Auf vigilae.org werden beide Lesungen bedient; bei einem dedizierten Deployment liegt die Aufrüstung des Speichers bei Ihrem Betreiber.
Diese Seite wird sich mit der API weiterentwickeln; die bestehenden Anker jedoch wechseln nie die Adresse — Sie können sie in Ihren Betriebslogs ablegen.