> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vu-one.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Errores y diagnóstico

> Los códigos de error de Face Analysis, los 500 con cuerpo en texto plano, el aborto de lote con imageNumber y qué errores se reintentan.

## 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):

```json theme={null}
{
  "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. |

<Warning>
  **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.
</Warning>

## 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**:

1. Omitir el campo `images`.
2. 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`):

<CodeGroup>
  ```json 401 sin Api-Key theme={null}
  {
    "statusCode": 401,
    "message": "Access denied due to missing subscription key. Make sure to include subscription key when making requests to an API."
  }
  ```

  ```json 401 api-key inválida theme={null}
  {
    "statusCode": 401,
    "message": "Access denied due to invalid subscription key. Make sure to provide a valid key for an active subscription."
  }
  ```

  ```json 404 ruta o método theme={null}
  {
    "statusCode": 404,
    "message": "Resource not found"
  }
  ```
</CodeGroup>

<Note>
  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.
</Note>

## 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**](mailto: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. |

<Card title="Volver a la introducción" icon="user-check" href="/vucs/face-analysis/introduccion">
  La regla de decisión, los endpoints y el mapa de operaciones de Face Analysis.
</Card>


## Related topics

- [Errores y diagnóstico](/vucs/id-analysis/errores.md)
- [Guía de integración](/vucs/face-analysis/integracion.md)
- [Face Analysis](/vucs/face-analysis/introduccion.md)
- [Autenticación con OAuth2 client credentials](/identity-link/autenticacion.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.