Errores y diagnóstico

Tabla de códigos

El campo code del cuerpo siempre coincide con el código HTTP — puede leer cualquiera de los dos, pero nunca decida solo con él.

Código	Qué significa	De quién es el problema	¿Reintentar?
`200`	El análisis corrió. Lea `message`, `id` y las validaciones — incluye «documento ilegible» y «dorso de otro documento».	—	No
`400`	La imagen no sirve o el flujo está mal armado. Ver los mensajes abajo.	Suyo o de la captura	Solo tras corregir
`401`	Api-key ausente, inválida o de otro ambiente.	Suyo	No
`404`	Ruta o método incorrecto (gateway), o template inexistente en el catálogo (servicio).	Suyo	No
`422`	Un campo no cumple el contrato. `detail[]` indica cuál — y devuelve el request completo.	Suyo	No
`500`	Error interno. La causa evitable conocida: enviar `relatedUuid` en `/front`.	Depende	Solo el esporádico
`503`	El motor de OCR no está disponible.	Del servicio	Sí, con backoff

200 no significa «documento aceptado». Significa que el análisis corrió: el documento ilegible (Cant get document fields) y el dorso cruzado (frontBackTemplateValidation: false) llegan con 200. La aceptación es la regla de Introducción.

Los `400` y sus mensajes

Mensaje	Causa	Qué hacer
`Image is too small {alto}x{ancho}, min size allowed 480x480.`	Alguno de los lados está por debajo de 480 px.	Capture en mayor resolución. Note que el tamaño se informa como alto×ancho.
`Image is not a valid, …`	El base64 no decodifica (prefijo `data:`, saltos de línea, truncado).	Valide el base64 antes de enviar.
`No document detected`	No se encontró un documento en la imagen.	Pida otra captura: documento completo, apoyado, sin reflejos.
`relatedUuid or documentId is required for back`	Falta `relatedUuid` en `/back`. A pesar del texto, solo `relatedUuid` satisface el requisito.	Envíe el `uuid` del `/front` previo.
`Bad relatedUuid`	Ese `uuid` no corresponde a un frente registrado.	Verifique que guardó el `uuid` de un `200` de `/front` —no el de un cuerpo de error—. Si llegó inmediatamente después del frente, espere unos segundos y reintente una vez.
`Document is too close to borders.`	`strictBorderMode` activo y el documento pegado al borde.	Pida otra captura con margen.

Todos los cuerpos de error del servicio tienen la misma forma:

{
  "uuid": "4ed11877-5f1a-4e51-9209-0866716c42da",
  "code": 400,
  "message": "Image is too small 160x240, min size allowed 480x480."
}

El uuid de un cuerpo de error se genera en el momento y no corresponde a ninguna transacción: no lo use como relatedUuid, pero sí inclúyalo en el ticket — le sirve a soporte para encontrar el intento en los logs.

El `422` devuelve su solicitud completa

{
  "uuid": "0dd2b667-6017-438d-9b34-b344ba5141c1",
  "code": 422,
  "message": "Bad request",
  "detail": [
    {
      "type": "missing",
      "loc": ["body", "info"],
      "msg": "Field required",
      "input": { "image": "/9j/4AAQSkZJRgABAQ..." }
    }
  ]
}

detail[].loc le dice exactamente qué campo está mal. Es un problema de código: se arregla en su lado y se reproduce siempre.

detail[].input es el eco literal de lo que usted envió — imagen base64 incluida. Un 422 puede pesar tanto como su request. Dos consecuencias: no registre cuerpos de error crudos en sus logs (terminaría almacenando los documentos de sus usuarios en texto plano), y no asuma que las respuestas de error son livianas al dimensionar buffers.

`401` y `404`: el gateway habla distinto

{
  "statusCode": 401,
  "message": "Access denied due to invalid subscription key. Make sure to provide a valid key for an active subscription."
}

{
  "statusCode": 404,
  "message": "Resource not found"
}

Estos cuerpos vienen del gateway y usan statusCode —no code— y no traen uuid. Dos detalles que ahorran tiempo:

Un 401 con la clave correcta suele ser ambiente equivocado: la api-key de homologación contra la URL de producción o viceversa.
El gateway responde 404 tanto para rutas inexistentes como para métodos incorrectos: un GET /front da 404, no 405. Si ve un 404 inesperado, revise el verbo además de la URL.

En los endpoints de catálogo, un template inexistente responde en cambio con el formato del servicio: {"code": 404, "message": "Template not found"}.

`500`: el evitable y el esporádico

La causa evitable conocida es enviar relatedUuid en /front — el campo es exclusivo de /back. Ese 500 es determinista: quite el campo y desaparece. Para el resto vale la prueba del determinismo: reintente una vez con el mismo cuerpo; si vuelve idéntico, el problema está en su solicitud — abra un ticket con el uuid en lugar de seguir reintentando. Un 500 esporádico sí amerita reintento con backoff, máximo 2 veces.

Abrir un ticket

Escriba a customer.support@vusecurity.com con:

Dato	Por qué
El `uuid` de la transacción	Es la clave con la que soporte encuentra el caso.
El ambiente	Homologación y producción pueden correr versiones distintas.
La marca de tiempo aproximada	Acota la ventana de logs a revisar.
El cuerpo completo de la respuesta	Con `code` y `message` tal cual llegaron — sin el `detail` de un `422`, que contiene la imagen.

No adjunte la imagen del documento salvo que soporte se la pida explícitamente y por un canal acordado: es el documento de identidad de una persona real.

Volver a la introducción

La regla de decisión, el flujo frente → dorso y la autenticación.

Empezar aquí

ID Analysis

Face Analysis

Antispoofing Facial

Connection Fingerprint

Tabla de códigos

Los `400` y sus mensajes

El `422` devuelve su solicitud completa

`401` y `404`: el gateway habla distinto

`500`: el evitable y el esporádico

Abrir un ticket

Volver a la introducción

​Tabla de códigos

​Los 400 y sus mensajes

​El 422 devuelve su solicitud completa

​401 y 404: el gateway habla distinto

​500: el evitable y el esporádico

​Abrir un ticket

Volver a la introducción

Tabla de códigos

Los `400` y sus mensajes

El `422` devuelve su solicitud completa

`401` y `404`: el gateway habla distinto

`500`: el evitable y el esporádico

Abrir un ticket