Every error, explained at a stable address.
This page is an operations reference, not a pitch. Every error class of the Connect API has a permanent anchor here; the API's error responses will point to these addresses. You get the probable cause and the fix — in that order. Back to the developer documentation.
Key missing, malformed or unknown
The API authenticates exclusively through the Authorization: Bearer vgk_… header — never through a session cookie. A revoked key becomes unknown the instant it is revoked.
The fix. Check that the header actually leaves (proxies sometimes strip it), that the key starts with vgk_ and that it has not been revoked from the firm's console. Since the secret is shown only at creation, a lost key is replaced, not recovered.
Expired key
Every key expires one year after creation — the expire_le date is visible in the firm's console from day one. The expiry 401 is explicit: it says the key existed and is no longer valid.
The fix. Create a new key, switch your calls over, revoke the old one. Plan this replacement in your operations rather than discovering it: the date is known a year ahead.
Insufficient scope
Keys carry lecture (read, the default) and/or ecriture (write). Qualifying an event requires ecriture; a read-only key receives a 403 whatever the resource.
The fix. Create a key carrying the needed scope — and only that one. Least privilege is deliberate: an integration that only reads has no reason to hold a write key.
Not found — or another firm's
A 404 means the resource does not exist or belongs to another firm. The API never distinguishes the two cases: distinguishing would reveal what exists elsewhere. Isolation is enforced at the database level, not just in application code.
The fix. Check the seq against the journal of the firm the key belongs to (GET /api/v1/evenements). If you integrate several firms, each firm has its own keys: a seq does not travel between firms.
Rate exceeded
60 requests per minute per key, by default (overridable per key). The response carries Retry-After and the X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset headers.
The fix. Honour Retry-After — no immediate retry. Hitting the limit while polling is almost always the sign of a full re-scan: the depuisSeq cursor never re-reads what has already been read.
The signature does not verify on your side
Your receiver must recompute v1 = HMAC-SHA256(secret, t + "." + body) from the raw body received, and reject any t older than 5 min. The classic failures: the body re-serialised before verification (reformatted JSON no longer has the same bytes), a clock drifting beyond the tolerance, and an ignored rotation — for 24 h the header carries one v1 per still-valid secret, and you must accept if any matches.
The fix. Verify against the raw bytes, sync your clock (NTP), test your verification during a rotation. The Node and Python snippets in the documentation do exactly this — copy them rather than rewriting them.
An event arrives twice
Delivery is at-least-once, in batches of at most 100, in journal order; the cursor only advances on your 2xx, batch by batch. A failure after reception but before the cursor advances causes a redelivery — that is the contract, not a defect.
The fix. The seq is your idempotency key: process each sequence exactly once, and only answer 2xx after persisting. An early 2xx followed by a crash is the only way to lose an event.
The journal looks incomplete or repeats itself
depuisSeq is strictly exclusive: only events with a higher seq are returned, sorted ascending, at most 500 per page. The response returns prochainSeq, to pass back as is. A page shorter than limite means the end of the journal.
The fix. Persist prochainSeq between runs and never recompute it yourself. Duplicates mean you restarted from a cursor too old; gaps mean you skipped a failed page without replaying it.
Parameter outside the schema
An unknown status, a disposition outside the list (planifie, traite, ecarte), a non-integer limite: the response names the offending field, and nothing else — error messages never carry file content.
The fix. The OpenAPI specification is the source: the enumerations and bounds it declares are the ones the server enforces, since it is served by it.
Insufficient scope (resource API)
The resource endpoints (/clients, /dossiers, documents, screening, alerts) require a fine-grained scope: clients:*, dossiers:*, pieces:*, criblage:* or the dedicated alertes:qualifier scope. A legacy lecture key grants every *:lecture scope and ecriture every *:ecriture — but alertes:qualifier is never inherited: qualifying an alert is a responsible officer's act, delegated by ticking that scope when the key is created.
The fix. Create a key carrying exactly the scopes your integration needs — and only those. The response's detail names the missing scope.
Resource not found — or another firm's
Same rule as #cloisonnement, applied to resources: a client, a file, a document or an alert that does not exist or that belongs to another firm gets the same 404. The API never tells the two cases apart.
The fix. Check the identifier against the listings of the firm the key belongs to. An identifier never travels from one firm to another.
Idempotency-Key header missing
Every creation or triggering POST (client, file, document, screening, beneficial owners) requires the Idempotency-Key header: a stable string of at most 200 characters, one per operation. Replaying the same key with the same body returns the same response, with no effect — your protection against duplicates on a network incident.
The fix. Generate the key before the first attempt (one UUID per business operation) and reuse it unchanged for every retry of that same operation.
Idempotency key reused with a different body
This Idempotency-Key has already been used for a different body within the last 24 hours. The key replays a response, it never overwrites one: reusing it for a new operation is almost always the sign of a key derived from a counter or a truncated date.
The fix. A new key for every new operation. Never derive the key from data that repeats across operations.
Sealed file: the register is frozen
Sealing freezes the file's integrity chain — that is its evidential value. A sealed file can no longer be edited, no longer receives documents and is no longer re-screened through this channel. Only alert qualification remains possible: it is written off-chain, the sealed head never moves.
The fix. Nothing to "correct": this is deliberate immutability. If data must change, that is a new due-diligence operation in the application, not a mutation of the sealed file.
Document format not accepted
Supporting documents accept PDF, JPG, JPEG, PNG and WEBP — the same formats as the application. The check is on the extension of the mandatory filename: a document without a valid file name is refused, whatever its content.
The fix. Convert before sending (a TIFF or HEIC scan converts to PDF or JPEG) and send the content as standard base64 in contenu, with a type among the stable a_doc_* codes.
Document over 6 MB
The limit applies to the decoded file (6 MB), the same as in the application and the collection portal. Since base64 adds a third of encoding overhead, the request body accepts up to 9 MB.
The fix. Compress the document (a colour 300 dpi scanned PDF almost always drops under the limit in greyscale) rather than splitting it.
Screening source unavailable
None of the file's entities could be checked against the lists: the source (official-list index or provider) did not answer. The API refuses to conclude — a "clean" report on top of a dead source would be the worst possible false negative. The failure is recorded on the file (erreurSource). A partial outage does not produce this 502: the 200 response keeps the matches of the entities that did answer and names the failed ones in erreurSourceEntites.
The fix. Replay the same call later, same Idempotency-Key: only success responses are memorised by idempotency — replaying after an error runs a real screening.
This page will evolve with the API; the existing anchors, however, never change address — you can store them in your operations logs.