> ## 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 Antispoofing Facial, cómo distinguir un problema de captura de un problema de código, qué reintentar y qué incluir en un ticket.

## Tabla de códigos

| Código | Qué significa | De quién es el problema | ¿Reintentar? |
| - | - | - | - |
| `200` | Análisis completado. Lea `spoofing` para el veredicto. | — | No |
| `400` | La imagen no cumple un requisito duro. | Suyo | No |
| `401` | Api-key ausente, inválida o de otro ambiente. | Suyo | No |
| `422` + `No Face Detected` | No se detectó un rostro en la imagen. | De la captura | No |
| `422` + `Bad request` y `detail[]` | El cuerpo de la solicitud no valida. | Suyo | No |
| `499` | El cliente cortó la conexión. | Su red o su timeout | Sí |
| `500` | Error del lado del servicio. | Depende — ver abajo | Solo si no es determinista |

<Warning>
  **`200` no significa aprobado.** Significa que el análisis se completó. Un intento de suplantación detectado también responde `200`, con `spoofing: true`. La aprobación exige las dos condiciones: `status === 200 && spoofing === false`.
</Warning>

## Los dos `422`

El mismo código cubre dos problemas completamente distintos, con dos dueños distintos. **Distíngalos por la presencia de `detail`, no por el código HTTP.**

<CodeGroup>
  ```json Imagen sin rostro theme={null}
  {
    "code": 422,
    "spoofing": true,
    "message": "No Face Detected",
    "id": "89f3f57e-...",
    "info": "onboarding-12345",
    "date": "2026-08-20",
    "time": "16:57:09"
  }
  ```

  ```json Cuerpo inválido theme={null}
  {
    "id": "4b3501fb-...",
    "code": 422,
    "message": "Bad request",
    "detail": [
      {
        "type": "string_type",
        "loc": ["body", "info"],
        "msg": "Input should be a valid string",
        "input": { "ref": "onboarding-12345" }
      }
    ]
  }
  ```
</CodeGroup>

**Sin rostro** es un problema de captura: pida una foto nueva con instrucciones concretas —rostro centrado, buena luz, sin objetos delante—. No es un bug y no se arregla reintentando la misma imagen. Note que esta respuesta trae `spoofing: true`: si su código aprueba por descarte, aquí aprueba a alguien de quien ni siquiera vio la cara.

**Cuerpo inválido** es un problema de código. `detail[].loc` le dice exactamente qué campo está mal; en el ejemplo, `info` se envió como objeto cuando el contrato pide una cadena. Se arregla en su lado y se reproduce siempre.

## `400`: la imagen no cumple un requisito duro

```json theme={null}
{
  "code": 400,
  "message": "Image should be larger than [224, 224]",
  "id": "f77e49f1-...",
  "info": "onboarding-12345"
}
```

Valide las dimensiones antes de llamar. Es más rápido, más barato y le permite pedirle al usuario una captura nueva sin esperar el viaje de ida y vuelta.

## `401`: credenciales

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

Note que este cuerpo usa `statusCode`, no `code`, y no trae `id`: se rechaza antes de crear una transacción. Revise que la cabecera se llame exactamente `Api-Key` y que la clave corresponda al ambiente de la URL base que está usando. Mezclar la clave de homologación con la URL de producción es la causa más común.

## `500`: no todos son del servicio

Un `500` parece un problema del proveedor, pero en la práctica la mayoría los provoca la solicitud: de los cinco cuerpos `500` observados en pruebas, cuatro se originaban en el pedido —una imagen que el decodificador no podía procesar, un payload malformado—.

**La prueba confiable es el determinismo:**

<Steps>
  <Step title="Reintente la misma solicitud una vez">
    Con el mismo cuerpo, sin modificar nada.
  </Step>

  <Step title="Compare el error">
    Si vuelve **el mismo** `error`, el problema está en su solicitud: revise la imagen y el payload. Si vuelve distinto o la llamada tiene éxito, fue transitorio.
  </Step>

  <Step title="Si es determinista, no siga reintentando">
    Abra un ticket con el `id` y el cuerpo del error. Reintentar solo agrega carga.
  </Step>
</Steps>

## Política de reintentos

```js theme={null}
const REINTENTABLE = (status, body) =>
  status === 499 ||
  (status === 500 && !/image|payload/i.test(body?.error ?? ""));

// Máximo 2 reintentos, con backoff exponencial. Nunca sobre spoofing: true.
```

<Warning>
  Nunca reintente una respuesta `200` con `spoofing: true`. Es un veredicto, no una falla. Un reintento que «arregla» un rechazo está aprobando fraude.
</Warning>

## Abrir un ticket

Escriba a [customer.support@vusecurity.com](mailto:customer.support@vusecurity.com) con:

| Dato | Por qué |
| - | - |
| El `id` de la transacción | Es la clave con la que soporte encuentra el caso. Sin él no hay búsqueda posible. |
| 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`, `message` y `errorMessage` tal cual llegaron. |

<Note>
  No adjunte la imagen original salvo que soporte se la pida explícitamente y por un canal acordado: es un dato biométrico de una persona real.
</Note>

<Card title="Volver a la introducción" icon="face-viewfinder" href="/vucs/antispoofing-facial/introduccion">
  La regla de decisión, los endpoints y la autenticación.
</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.