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.
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.
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.
Die Abhilfe. Erstellen Sie einen neuen Schlüssel, stellen Sie Ihre Aufrufe um, widerrufen Sie den alten. Planen Sie diesen Wechsel in Ihrem Betrieb ein, statt ihn zu entdecken: Das Datum ist ein Jahr im Voraus bekannt.
Unzureichender Scope
Schlüssel tragen lecture (Lesen, der Standard) und/oder ecriture (Schreiben). Das Qualifizieren eines Ereignisses erfordert ecriture; ein Nur-Lese-Schlüssel erhält einen 403, gleich für welche Ressource.
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.
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.
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.
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.
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.
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.
Diese Seite wird sich mit der API weiterentwickeln; die bestehenden Anker jedoch wechseln nie die Adresse — Sie können sie in Ihren Betriebslogs ablegen.