Cada error, explicado en una dirección estable.
Esta página es una referencia de operaciones, no un argumento de venta. Cada clase de error de la API Connect tiene aquí un ancla permanente; las respuestas de error de la API apuntarán a estas direcciones. Encontrará la causa probable y la solución — en ese orden. Volver a la documentación para desarrolladores.
Clave ausente, malformada o desconocida
La API se autentica exclusivamente mediante la cabecera Authorization: Bearer vgk_… — nunca mediante una cookie de sesión. Una clave revocada pasa a ser desconocida en el mismo instante de su revocación.
La solución. Compruebe que la cabecera sale de verdad (a veces los proxies la eliminan), que la clave empieza por vgk_ y que no ha sido revocada desde la consola del despacho. Como el secreto solo se muestra en la creación, una clave perdida se sustituye, no se recupera.
Clave caducada
Toda clave caduca un año después de su creación — la fecha expire_le es visible en la consola del despacho desde el primer día. El 401 de caducidad es explícito: dice que la clave existió y que ya no es válida.
La solución. Cree una clave nueva, migre sus llamadas, revoque la antigua. Planifique esta sustitución en sus operaciones en lugar de descubrirla: la fecha se conoce con un año de antelación.
Scope insuficiente
Las claves llevan lecture (lectura, por defecto) y/o ecriture (escritura). Calificar un evento requiere ecriture; una clave de solo lectura recibe un 403 sea cual sea el recurso.
La solución. Cree una clave con el scope necesario — y solo ese. El mínimo privilegio es deliberado: una integración que solo lee no tiene motivo para poseer una clave de escritura.
No encontrado — o de otro despacho
Un 404 significa que el recurso no existe o que pertenece a otro despacho. La API nunca distingue los dos casos: distinguirlos revelaría lo que existe en otra parte. El aislamiento se impone a nivel de base de datos, no solo en el código de la aplicación.
La solución. Compruebe el seq contra el diario del despacho al que pertenece la clave (GET /api/v1/evenements). Si integra varios despachos, cada despacho tiene sus propias claves: un seq no viaja entre despachos.
Límite de peticiones superado
60 solicitudes por minuto y clave, por defecto (ajustable clave por clave). La respuesta lleva Retry-After y las cabeceras X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.
La solución. Respete Retry-After — nada de reintentos inmediatos. Alcanzar el límite durante un sondeo es casi siempre señal de un rebarrido completo: el cursor depuisSeq nunca relee lo ya leído.
La firma no se verifica de su lado
Su receptor debe recalcular v1 = HMAC-SHA256(secret, t + "." + body) a partir del cuerpo bruto recibido, y rechazar todo t de más de 5 min. Los fallos clásicos: el cuerpo reserializado antes de la verificación (un JSON reformateado ya no tiene los mismos bytes), un reloj que deriva más allá de la tolerancia, y una rotación ignorada — durante 24 h la cabecera lleva un v1 por cada secreto aún válido, y debe aceptar si cualquiera coincide.
La solución. Verifique contra los bytes brutos, sincronice su reloj (NTP), pruebe su verificación durante una rotación. Los fragmentos Node y Python de la documentación hacen exactamente esto — cópielos en lugar de reescribirlos.
Un evento llega dos veces
La entrega es at-least-once, en lotes de 100 como máximo, en el orden del diario; el cursor solo avanza con su 2xx, lote a lote. Un fallo después de la recepción pero antes de que avance el cursor provoca una nueva entrega — es el contrato, no un defecto.
La solución. El seq es su clave de idempotencia: procese cada secuencia exactamente una vez, y no responda 2xx hasta haber persistido. Un 2xx prematuro seguido de una caída es la única manera de perder un evento.
El diario parece incompleto o se repite
depuisSeq es estrictamente exclusivo: solo se devuelven los eventos con un seq superior, ordenados de forma ascendente, 500 como máximo por página. La respuesta devuelve prochainSeq, que se reenvía tal cual. Una página más corta que limite significa el final del diario.
La solución. Persista prochainSeq entre ejecuciones y nunca lo recalcule usted mismo. Los duplicados significan que reanudó desde un cursor demasiado antiguo; los huecos, que saltó una página fallida sin reprocesarla.
Parámetro fuera del esquema
Un estado desconocido, una disposición fuera de la lista (planifie, traite, ecarte), un limite no entero: la respuesta nombra el campo en cuestión, y nada más — los mensajes de error nunca llevan contenido de expedientes.
La solución. La especificación OpenAPI es la fuente: las enumeraciones y los límites que declara son los que el servidor impone, puesto que es él quien la sirve.
Scope insuficiente (API de recursos)
Los endpoints de recursos (/clients, /dossiers, documentos, cribado, alertas) requieren un scope de grano fino: clients:*, dossiers:*, pieces:*, criblage:* o el scope dedicado alertes:qualifier. Una clave lecture heredada concede todos los scopes *:lecture y una ecriture todos los *:ecriture — pero alertes:qualifier nunca se hereda: calificar una alerta es un acto del responsable de cumplimiento, delegado marcando ese scope al crear la clave.
La solución. Cree una clave con exactamente los scopes que su integración necesita — y solo esos. El detail de la respuesta nombra el scope que falta.
Recurso no encontrado — o de otro despacho
La misma regla que #cloisonnement, aplicada a los recursos: un cliente, un expediente, un documento o una alerta que no existe o que pertenece a otro despacho recibe el mismo 404. La API nunca separa los dos casos.
La solución. Compruebe el identificador contra los listados del despacho al que pertenece la clave. Un identificador nunca viaja de un despacho a otro.
Falta la cabecera Idempotency-Key
Todo POST de creación o de disparo (cliente, expediente, documento, cribado, titulares reales) requiere la cabecera Idempotency-Key: una cadena estable de 200 caracteres como máximo, una por operación. Repetir la misma clave con el mismo cuerpo devuelve la misma respuesta, sin efecto alguno — su protección contra los duplicados en un incidente de red.
La solución. Genere la clave antes del primer intento (un UUID por operación de negocio) y reutilícela sin cambios en cada reintento de esa misma operación.
Clave de idempotencia reutilizada con otro cuerpo
Esta Idempotency-Key ya se ha usado con un cuerpo diferente en las últimas 24 horas. La clave repite una respuesta, nunca la sobrescribe: reutilizarla para una operación nueva es casi siempre señal de una clave derivada de un contador o de una fecha truncada.
La solución. Una clave nueva para cada operación nueva. Nunca derive la clave de datos que se repiten entre operaciones.
Expediente sellado: el registro está congelado
El sellado congela la cadena de integridad del expediente — ahí reside su valor probatorio. Un expediente sellado ya no puede editarse, ya no recibe documentos y ya no se recriba por este canal. Solo sigue siendo posible la calificación de alertas: se escribe fuera de la cadena, la cabeza sellada nunca se mueve.
La solución. Nada que «corregir»: es una inmutabilidad deliberada. Si un dato debe cambiar, eso es una nueva operación de diligencia debida en la aplicación, no una mutación del expediente sellado.
Formato de documento no aceptado
Los documentos justificativos aceptan PDF, JPG, JPEG, PNG y WEBP — los mismos formatos que la aplicación. La comprobación se hace sobre la extensión del filename obligatorio: un documento sin nombre de archivo válido se rechaza, sea cual sea su contenido.
La solución. Convierta antes de enviar (un escaneo TIFF o HEIC se convierte a PDF o JPEG) y envíe el contenido en base64 estándar en contenu, con un type de entre los códigos estables a_doc_*.
Documento de más de 6 MB
El límite se aplica al archivo descodificado (6 MB), igual que en la aplicación y en el portal de recogida. Como el base64 añade un tercio de sobrecarga de codificación, el cuerpo de la petición acepta hasta 9 MB.
La solución. Comprima el documento (un PDF escaneado en color a 300 ppp casi siempre baja del límite en escala de grises) antes que trocearlo.
Fuente de cribado no disponible
Ninguna de las entidades del expediente pudo cotejarse con las listas: la fuente (índice de listas oficiales o proveedor) no respondió. La API se niega a concluir — un informe «limpio» sobre una fuente muerta sería el peor falso negativo posible. El fallo queda registrado en el expediente (erreurSource). Una caída parcial no produce este 502: la respuesta 200 conserva las coincidencias de las entidades que sí respondieron y nombra las fallidas en erreurSourceEntites.
La solución. Repita la misma llamada más tarde, con la misma Idempotency-Key: la idempotencia solo memoriza las respuestas de éxito — reintentar tras un error ejecuta un cribado real.
Esta página evolucionará con la API; las anclas existentes, en cambio, nunca cambian de dirección — puede almacenarlas en sus registros de operaciones.