Chaque erreur, expliquée à une adresse stable.
Cette page est une référence d'exploitation, pas un argumentaire. Chaque classe d'erreur de l'API Connect y possède une ancre pérenne ; les réponses d'erreur de l'API renverront vers ces adresses. Vous y trouvez la cause probable et le geste qui corrige — dans cet ordre. Retour à la documentation développeurs.
Clé absente, mal formée ou inconnue
L'API s'authentifie exclusivement par l'en-tête Authorization: Bearer vgk_… — jamais par cookie de session. Une clé révoquée redevient inconnue à l'instant de sa révocation.
Le geste. Vérifiez que l'en-tête part bien (les proxys le retirent parfois), que la clé commence par vgk_ et qu'elle n'a pas été révoquée depuis la console du cabinet. Le secret n'étant montré qu'à la création, une clé perdue se remplace, elle ne se retrouve pas.
Clé expirée
Chaque clé expire un an après sa création — la date expire_le est visible dans la console du cabinet dès la création. Le 401 d'expiration est explicite : il dit que la clé a existé et n'est plus valide.
Le geste. Créez une nouvelle clé, basculez vos appels, révoquez l'ancienne. Prévoyez ce remplacement dans votre exploitation plutôt que de le découvrir : la date est connue un an à l'avance.
Scope insuffisant
Les clés portent lecture (défaut) et/ou ecriture. La qualification d'un événement exige ecriture ; une clé de lecture reçoit un 403, quelle que soit la ressource.
Le geste. Créez une clé portant le scope nécessaire — et seulement lui. Le moindre privilège est voulu : une intégration qui ne fait que lire n'a aucune raison de détenir une clé d'écriture.
Introuvable — ou d'un autre cabinet
Un 404 signifie que la ressource n'existe pas ou qu'elle appartient à un autre cabinet. L'API ne distingue jamais les deux cas : distinguer reviendrait à révéler ce qui existe ailleurs. Le cloisonnement est appliqué au niveau de la base de données, pas seulement dans le code.
Le geste. Vérifiez le seq contre le journal du cabinet dont la clé est issue (GET /api/v1/evenements). Si vous intégrez plusieurs cabinets, chaque cabinet a ses clés : un seq ne voyage pas d'un cabinet à l'autre.
Débit dépassé
60 requêtes par minute et par clé, par défaut (surchargeable par clé). La réponse porte Retry-After et les en-têtes X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.
Le geste. Respectez Retry-After — pas de retry immédiat. Si vous atteignez la limite en polling, c'est presque toujours le signe d'un re-balayage complet : le curseur depuisSeq ne relit jamais ce qui a déjà été lu.
La signature ne se vérifie pas chez vous
Votre récepteur doit recalculer v1 = HMAC-SHA256(secret, t + "." + corps) depuis le corps brut reçu, et rejeter tout t au-delà de 5 minutes. Les échecs classiques : le corps re-sérialisé avant vérification (un JSON reformaté n'a plus les mêmes octets), une horloge qui dérive au-delà de la tolérance, et une rotation ignorée — pendant 24 h, l'en-tête porte un v1 par secret encore valide, il faut accepter si l'un correspond.
Le geste. Vérifiez sur les octets bruts, synchronisez l'horloge (NTP), testez votre vérification pendant une rotation. Les extraits Node et Python de la documentation font exactement cela — copiez-les plutôt que de les réécrire.
Un événement arrive deux fois
La livraison est at-least-once, par lots de 100 au maximum, dans l'ordre du journal ; le curseur n'avance que sur votre réponse 2xx, lot par lot. Un échec après réception mais avant l'avance du curseur provoque une relivraison — c'est le contrat, pas un défaut.
Le geste. Le seq est votre identifiant d'idempotence : traitez chaque séquence une seule fois, et ne répondez 2xx qu'après avoir persisté. Un 2xx anticipé suivi d'un crash est le seul moyen de perdre un événement.
Le journal semble incomplet ou se répète
depuisSeq est strictement exclusif : seuls les événements de seq supérieur sont rendus, triés croissant, au plus 500 par page. La réponse rend prochainSeq, à repasser tel quel. Une page plus courte que limite signifie la fin du journal.
Le geste. Persistez prochainSeq entre deux passages et ne le recalculez pas vous-même. Si vous voyez des doublons, vous repartez d'un curseur trop ancien ; si vous voyez des trous, vous avez sauté une page en erreur sans la rejouer.
Paramètre hors schéma
Un statut inconnu, une disposition hors liste (planifie, traite, ecarte), une limite non entière : la réponse nomme le champ en cause, et rien d'autre — les messages d'erreur ne transportent jamais de contenu de dossier.
Le geste. La spécification OpenAPI est la source : les énumérations et bornes qu'elle déclare sont celles que le serveur applique, puisqu'elle est servie par lui.
Scope insuffisant (API de ressources)
Les endpoints de ressources (/clients, /dossiers, pièces, criblage, alertes) exigent un scope fin : clients:*, dossiers:*, pieces:*, criblage:* ou le scope dédié alertes:qualifier. Une clé historique lecture vaut chaque *:lecture et ecriture chaque *:ecriture — mais alertes:qualifier ne s'hérite jamais : qualifier une alerte est un acte de responsable, délégué en cochant ce scope à la création de la clé.
Le geste. Créez une clé portant exactement les scopes dont votre intégration a besoin — et seulement eux. Le detail de la réponse nomme le scope manquant.
Ressource introuvable — ou d'un autre cabinet
Même règle que #cloisonnement, appliquée aux ressources : un client, un dossier, une pièce ou une alerte qui n'existe pas ou qui appartient à un autre cabinet répond le même 404. L'API ne distingue jamais les deux cas.
Le geste. Vérifiez l'identifiant contre les listes du cabinet dont la clé est issue. Un identifiant ne voyage pas d'un cabinet à l'autre.
En-tête Idempotency-Key absent
Tout POST de création ou de déclenchement (client, dossier, pièce, criblage, bénéficiaires effectifs) exige l'en-tête Idempotency-Key : une chaîne stable de 200 caractères au plus, une par opération. Rejouer la même clé avec le même corps rend la même réponse, sans effet — c'est votre protection contre les doublons sur incident réseau.
Le geste. Générez la clé avant le premier essai (un UUID par opération métier) et réutilisez-la telle quelle pour chaque retry de la même opération.
Clé d'idempotence réutilisée avec un autre corps
Cette Idempotency-Key a déjà servi pour un corps différent dans les dernières 24 heures. La clé rejoue une réponse, elle n'en écrase jamais une : la réutiliser pour une opération nouvelle est presque toujours le signe d'une clé fabriquée depuis un compteur ou une date tronquée.
Le geste. Une clé nouvelle par opération nouvelle. Ne dérivez jamais la clé de données qui se répètent d'une opération à l'autre.
Dossier scellé : le registre est figé
Le scellement fige la chaîne d'intégrité du dossier — c'est sa valeur de preuve. Un dossier scellé ne s'édite plus, ne reçoit plus de pièce et ne se re-crible plus par ce canal. Seule la qualification d'une alerte reste possible : elle s'écrit hors chaîne, la tête scellée ne bouge pas.
Le geste. Rien à « corriger » : c'est l'immuabilité voulue. Si une donnée doit évoluer, c'est une nouvelle opération de vigilance dans l'application, pas une mutation du dossier scellé.
Format de pièce non accepté
Les pièces justificatives acceptent PDF, JPG, JPEG, PNG et WEBP — les mêmes formats que l'application. Le contrôle porte sur l'extension du filename, obligatoire : une pièce sans nom de fichier valide est refusée, quel que soit son contenu.
Le geste. Convertissez avant l'envoi (un scan TIFF ou HEIC se convertit en PDF ou JPEG) et envoyez le contenu en base64 standard dans contenu, avec un type parmi les codes stables a_doc_*.
Pièce au-delà de 6 Mo
La borne s'applique au fichier décodé (6 Mo), la même que dans l'application et le portail de collecte. Le base64 ajoutant un tiers d'encodage, le corps de requête accepte jusqu'à 9 Mo.
Le geste. Compressez le document (un PDF scanné en 300 dpi couleur descend presque toujours sous la borne en niveaux de gris) plutôt que de le découper.
Source de criblage indisponible
Aucune des entités du dossier n'a pu être confrontée aux listes : la source (index de listes officielles ou fournisseur) n'a pas répondu. L'API refuse de conclure — un rapport « propre » au-dessus d'une source morte serait le pire faux négatif possible. L'échec est tracé au dossier (erreurSource). Une panne partielle ne produit pas ce 502 : la réponse 200 conserve les correspondances des entités qui ont répondu et nomme celles en échec dans erreurSourceEntites.
Le geste. Rejouez le même appel plus tard, même Idempotency-Key : seules les réponses de succès sont mémorisées par l'idempotence — le rejeu après une erreur relance un criblage réel.
Cette page évoluera avec l'API ; les ancres existantes, elles, ne changent pas d'adresse — vous pouvez les stocker dans vos journaux d'exploitation.