Errores y diagnóstico

Los códigos, de un vistazo

Código	Quién lo emite	Qué significa	Qué hacer
`200`	Servicio	La operación corrió. No implica match ni buena calidad: evalúe `biometric` e `inferenceConfidence`.	Aplicar la regla de decisión.
`400`	Servicio	Un problema con una imagen u operación concreta: sin rostro, muy chica, base64 inválido, operación inexistente.	Corregir la imagen u operación indicada. No reintentar igual.
`401`	Gateway	Falta la cabecera `Api-Key` o la clave no vale para este ambiente.	Verificar clave y ambiente.
`404`	Gateway	Ruta inexistente o método equivocado (un `GET /inference` da 404, no 405).	Verificar ruta y método.
`422`	Servicio	El cuerpo no es JSON válido, no es un objeto, o `info` viola su formato.	Corregir el cuerpo.
`500`	Servicio	O bien un error transitorio, o bien su solicitud: `images` ausente u `operations` desalineado. Cuerpo en texto plano.	Ver la sección de los 500.

Los `400`: un solo error, con índice

El cuerpo del 400 indica la imagen culpable con imageNumber (base 0):

{
  "id": "7be2f9a1-...",
  "code": 400,
  "message": "Face not found",
  "imageNumber": 1
}

Mensaje	Causa
`Face not found`	No se detectó un rostro en la imagen indicada. Pida otra captura.
`Image is too small`	La imagen no llega al mínimo duro de 160 × 160 px.
`Image is not valid`	El contenido de `images[i]` no es base64 decodificable.
`Operation is not valid`	Un nombre de operación no existe, o envió `operations` como lista simple en vez de lista de listas.

Una imagen mala aborta el lote entero. Si envía 4 imágenes y la tercera no tiene rostro, recibe un solo 400 con imageNumber: 2 y ningún resultado — no hay resultados parciales. Si su flujo tolera fallas por imagen, envíe una solicitud por imagen.

Los `500` vienen en texto plano

Dos errores de solicitud no devuelven un 400 prolijo sino un 500 con el cuerpo literal Internal Server Error — no es JSON:

Omitir el campo images.
Enviar una lista operations más corta que images.

Su cliente HTTP no debe asumir que toda respuesta es JSON: envuelva el parseo y trate el fallo de parseo como error, nunca como aprobación. Cómo distinguir un 500 transitorio de uno suyo: reinténtelo una vez con backoff. Si vuelve idéntico, es determinístico — lo causa su solicitud; valide images y la alineación de operations en su código y no siga reintentando.

Los errores del gateway: otro formato

El 401 y el 404 no los emite el servicio sino el gateway, y su cuerpo tiene otro formato (statusCode en vez de code):

{
  "statusCode": 401,
  "message": "Access denied due to missing subscription key. Make sure to include subscription key when making requests to an API."
}

{
  "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"
}

Un 401 con una clave que «siempre funcionó» suele ser mezcla de ambientes: la clave de homologación contra la URL de producción o viceversa. Verifique el par URL + clave antes de escalar.

Los `422`: violaciones del contrato

Cuerpo no-JSON, cuerpo que no es un objeto, o info fuera de rango (2–256 caracteres) devuelven 422 con el detalle campo por campo en detail. Son errores de programación, no de datos: corríjalos en desarrollo, no los maneje en producción.

Política de reintentos

Error	¿Reintentar?
`500` esporádico (no se repite idéntico)	Sí, backoff, máximo 2.
`500` determinístico	No: corregir la solicitud.
`400` / `401` / `404` / `422`	No: corregir imagen, credencial, ruta o cuerpo.
No-match (`200` con puntaje bajo)	Nunca con la misma imagen: el resultado es determinístico. Pida otra captura.
`spoofing: true`	Nunca con la misma imagen.

Si tiene que abrir un ticket

Escriba a customer.support@vusecurity.com con:

Dato	Dónde está
El `id` de la transacción	En el cuerpo de la respuesta (también en los `400`).
El ambiente	Homologación o producción.
Fecha y hora aproximadas	Con zona horaria.
El código HTTP y el mensaje	Sin adjuntar imágenes en base64 ni cuerpos crudos con datos personales.

Volver a la introducción

La regla de decisión, los endpoints y el mapa de operaciones de Face Analysis.

Empezar aquí

ID Analysis

Face Analysis

Antispoofing Facial

Connection Fingerprint

Los códigos, de un vistazo

Los `400`: un solo error, con índice

Los `500` vienen en texto plano

Los errores del gateway: otro formato

Los `422`: violaciones del contrato

Política de reintentos

Si tiene que abrir un ticket

Volver a la introducción

​Los códigos, de un vistazo

​Los 400: un solo error, con índice

​Los 500 vienen en texto plano

​Los errores del gateway: otro formato

​Los 422: violaciones del contrato

​Política de reintentos

​Si tiene que abrir un ticket

Volver a la introducción

Los códigos, de un vistazo

Los `400`: un solo error, con índice

Los `500` vienen en texto plano

Los errores del gateway: otro formato

Los `422`: violaciones del contrato

Política de reintentos

Si tiene que abrir un ticket