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

> Códigos de respuesta de ID Analysis, el 422 que devuelve su solicitud completa, los errores del flujo frente-dorso y qué reintentar.

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

<Warning>
  **`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](/vucs/id-analysis/introduccion#la-regla-de-decision).
</Warning>

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

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

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

## El `422` devuelve su solicitud completa

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

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

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

<CodeGroup>
  ```json 401 · credenciales 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>

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

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

<Card title="Volver a la introducción" icon="id-card" href="/vucs/id-analysis/introduccion">
  La regla de decisión, el flujo frente → dorso y la autenticación.
</Card>


## Related topics

- [Errores y diagnóstico](/vucs/face-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.