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.
El mismo 401 lleva "motif": "fin_option_api" cuando la clave se ha detenido porque la API ya no forma parte de la suscripción del despacho. La fecha de esa parada se indicó en un correo electrónico a los administradores del despacho o, en su defecto, a la dirección de facturación del despacho, y después se anunció en la cabecera Sunset de cada respuesta a una llamada aceptada (calendario en #cle-expiree). Sin motivo, también puede deberse a una suscripción suspendida: la suspensión corta las claves en el acto.
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. Con "motif": "fin_option_api", ni la cabecera ni la clave están en causa: el administrador del despacho nos escribe a contact@vigilae.org para que la API vuelva a la suscripción, y la misma clave vuelve a aceptarse en cuanto eso ocurre, hasta su propia fecha de caducidad.
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.
Una clave API también puede dejar de aceptarse antes de esa fecha, cuando la API ya no forma parte de la suscripción del despacho. La parada llega entonces al menos 30 días después de un primer correo electrónico, en la fecha que indica un segundo correo, enviado al menos 7 días antes; ambos se dirigen a los administradores del despacho o, en su defecto, a la dirección de facturación del despacho. En cuanto se fija, esa fecha puede leerse en la consola del despacho (campo coupure_le de GET /connect/cles), y cada respuesta a una llamada aceptada la anuncia en la cabecera Sunset hasta que llega. Pasada esa fecha, la llamada recibe el 401 descrito en #authentification, con "motif": "fin_option_api"; si la API vuelve a la suscripción, la clave vuelve a aceptarse, hasta su propia fecha de caducidad.
La solución. Cree una clave nueva, migre sus llamadas, revoque la antigua. Para una clave API, hace falta además que la API siga formando parte de la suscripción del despacho: sin ella, la consola se niega a crear una. Planifique esta sustitución en sus operaciones en lugar de descubrirla.
Scope insuficiente
Las claves llevan los scopes marcados en su creación: los generales lecture (lectura, por defecto) y ecriture (escritura), o los finos por recurso (clients:lecture, pieces:ecriture, origine-fonds:lecture, journal:lecture…).
La herencia es por sufijo, en un solo sentido: lecture cubre todo *:lecture, ecriture todo *:ecriture — nunca al revés; un scope fino solo se abre a sí mismo.
Seis scopes quedan fuera de ese par y no se heredan de ninguna clave general: alertes:qualifier, embed:emettre, adversemedia:consulter, conformite:consulter, dispositif:consulter, integrite:consulter. Calificar un evento, emitir un token de incrustación, leer la prensa desfavorable de un expediente o una nota de llevanza nunca se deriva de un derecho de lectura general: cada uno se marca aparte.
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, y una clave amplia nunca suplirá un scope que no se haya delegado de forma explícita.
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.
Esta cuenta ya existe
Un POST /scim/v2/Users sobre un userName ya aprovisionado para este despacho responde 409 con scimType: uniqueness. La unicidad la sostiene una restricción de base de datos, no una caché: dos creaciones simultáneas no pueden producir dos cuentas.
La solución. Trate el 409 como un éxito idempotente, no como un error: vuelva a leer la cuenta con ?filter=userName eq "…" y continúe con el identificador devuelto. Un conector que reintenta en bucle ante un 409 nunca creará nada más.
Esta cuenta queda fuera del alcance del directorio
Un directorio no puede degradar ni desactivar una cuenta que ostenta poderes de administración del despacho: la petición se rechaza con scimType: mutability y queda registrada. Sin ese límite, un conector que adopte la dirección del responsable de cumplimiento cerraría el despacho a quien responde por él.
La solución. Retire a esa persona del perímetro sincronizado, o cambie su rol desde Vigilae. El rechazo afecta solo a esta cuenta: el resto del lote se aplica con normalidad.
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.
Campo cuyo valor es demasiado largo: Nacionalidad
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.
Otro intento con esta clave sigue en curso
Dos solicitudes con la misma Idempotency-Key han llegado juntas: la primera se ejecuta, la segunda se rechaza antes de cualquier efecto. Ese rechazo es lo que evita el duplicado. El caso habitual: un proxy devuelve 502 o 504 mientras el servidor sigue trabajando, y su cliente repite la llamada. La cabecera Retry-After indica en cuántos segundos repetirla.
La solución. Repita la misma solicitud, tal cual, con la misma clave, pasado el plazo anunciado: recibirá la respuesta del primer intento. No fabrique nunca una clave nueva para «desbloquear»: sería crear el duplicado que la clave evita.
Entorno de pruebas: cuota alcanzada
Un entorno de pruebas tiene límites fijos: 200 fichas de cliente, 50 expedientes y 40 documentos por expediente. Toda creación o aportación que rebase alguno de ellos se rechaza antes de cualquier escritura, y el rechazo indica cuál: los campos ressource, quota y courant recogen el recurso, el tope y el recuento en el momento del rechazo. Si dos creaciones simultáneas se disputan la última plaza, solo pasa una. Modificar una ficha o un expediente existente no consume nada.
La solución. Estas cuotas no se negocian, y repetir la solicitud devolverá el mismo rechazo. Restablezca el entorno de pruebas desde su cuenta — vuelve a partir de los datos de demostración — o contrate una suscripción: estas cuotas solo se aplican a los entornos de pruebas.
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.
Expediente cerrado: la relación de negocio ha finalizado
La relación se ha cerrado en la aplicación: el expediente ya no acepta escrituras por la API — ni edición, ni documento, ni cribado, ni titulares reales. Las lecturas siguen abiertas: un expediente cerrado se consulta y se exporta durante todo el plazo de conservación.
La solución. Reabrir la relación es un acto humano y trazado, en la aplicación; la API no lo hace en su lugar. Si la operación es nueva, abra un expediente nuevo en vez de reanimar el antiguo.
Expediente depurado: los datos se han borrado
El plazo de conservación ha vencido y los datos del expediente se han borrado. Solo queda la traza de auditoría, que acredita que un expediente existió y que fue depurado en la fecha indicada; ya no acepta ninguna escritura.
La solución. Nada que corregir y nada que repetir: el borrado es definitivo y deliberado. Un identificador de expediente depurado conservado en sus sistemas es un histórico, nunca un destino de escritura.
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.
Widgets incrustados no activados en esta instancia
La emisión mediante POST /api/v1/embed/jetons depende de los orígenes declarados de su despacho — esa lista es lo que gobierna la CSP frame-ancestors del shell incrustado. Este 501 indica que la instancia que ha llamado no dispone de ese almacén: la superficie de embed queda inerte ahí por construcción, y lo declara en vez de emitir un token que ningún origen podría mostrar jamás. No debe confundirse con el 400 que recibe un despacho cuyos orígenes aún no están declarados.
La solución. Este 501 habla de la instancia, no de su solicitud. En vigilae.org, el administrador de su despacho declara él mismo los orígenes, en la pantalla «Integraciones y seguridad» (el recuadro de la sección de widgets indica dónde); repita después la misma llamada. Nada que cambiar en su código: la solicitud era correcta, la instancia no estaba lista.
Superficie no disponible en esta instancia
Dos lecturas de base — GET /api/v1/dossiers/{id}/origine-fonds y GET /api/v1/dossiers/{id}/exigences — se apoyan en almacenes que no todas las instancias llevan. Cuando falta uno, la API lo dice en lugar de servir una lista vacía: «nada que señalar» y «no se ha leído nada» son hechos opuestos, y confundirlos haría pasar un expediente que nadie ha consultado por un expediente sin reservas. Este 501 habla de la instancia llamada, nunca de su petición ni del expediente.
La solución. No reintente en bucle: nada cambiará mientras la instancia no lleve ese almacén. Trate este código como «dato no disponible aquí» y, sobre todo, no lo cuente como un cero en sus cuadros de mando — así es como una medición ausente se convierte en una cifra falsa. En vigilae.org ambas lecturas se sirven; en un despliegue dedicado, la actualización del almacén corresponde a su operador.
Esta página evolucionará con la API; las anclas existentes, en cambio, nunca cambian de dirección — puede almacenarlas en sus registros de operaciones.