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

# Validación y manejo de errores de Face Auth URL

> Referencia por etapas del flujo Face Auth URL: fallos de validación de QueryString, fallos de precarga y fallos de autenticación, junto con los mensajes que los usuarios ven realmente.

<Info>
  Esta página cubre los fallos del flujo **A. Face Auth URL** (consulte [Comenzar con FaceAuth](/es/idcheck/add-on/faceauth-overview)).

  Para los códigos de fallo y códigos de error del flujo **B. API POST /faceauth**, consulte [POST/Faceauth](/es/idcheck/add-on/post-faceauth#6-códigos-de-error). Los dos flujos usan pipelines de verificación distintos, por lo que los códigos devueltos y el manejo de fallos también difieren.
</Info>

## 1. Tres etapas donde ocurren los fallos

En el flujo Face Auth URL, la pantalla que ve el usuario depende de dónde ocurre el fallo.

<Steps>
  <Step title="Entrada — validación de QueryString y token">
    Valida `pid`, el `sid` cifrado y `token` en la URL. Si falla, el usuario es **redirigido a una página de error** y la verificación no comienza. → [2. Fallos de validación en la etapa de entrada](#2-fallos-de-validación-en-la-etapa-de-entrada)
  </Step>

  <Step title="Precarga — consulta de proyecto y submission">
    Recupera las opciones del proyecto FaceAuth y el submission de ID Check referenciado. Si falla, el usuario es **redirigido a una página de error**. → [3. Errores de servidor en la etapa de precarga](#3-errores-de-servidor-en-la-etapa-de-precarga)
  </Step>

  <Step title="Autenticación — evaluación tras la captura de la selfie">
    Ejecuta comparación facial, liveness y detección de oclusión sobre la selfie capturada. Según el tipo de fallo, se muestra un **AlertPopup** o una **pantalla de resultado de rechazo**. → [4. Mensajes al usuario en la etapa de autenticación](#4-mensajes-al-usuario-en-la-etapa-de-autenticación)
  </Step>
</Steps>

## 2. Fallos de validación en la etapa de entrada

### 2-1. Parámetros obligatorios ausentes

**Face Auth no se ejecuta sin cadena de consulta.** Una URL que solo lleve `pid` no inicia la verificación; la forma mínima ejecutable requiere el `sid` de referencia, cifrado y enviado dentro de `encrypted`.

| Código de error | URL                                | Mensaje al usuario                                                                                                                                           | Condición                                                          |
| --------------- | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------ |
| `PV-40015`      | `/error-page/missing-faceauth-pid` | "Authentication information is missing"<br />Required parameters (pid or sid) for face authentication are missing. Please access again via the correct link. | Se ingresa al flujo Face Auth sin `pid` o sin un `sid` descifrado. |

<Warning>
  `sid` **debe incluirse dentro de `encrypted`**. Un `sid` en texto plano no se reconoce y produce `PV-40015`. Para el procedimiento de cifrado, consulte [Cifrado de Cadena de Consulta](/es/idcheck/getting-started/encrypt-and-decrypt-data/overview#2-cifrado-de-cadena-de-consulta).
</Warning>

<Note>
  **Un valor de `encrypted` mal formado puede mostrar una pantalla de "Página no encontrada" en lugar de la página con código de error anterior.**

  Caso observado (2026-08): el `pid` y la codificación de URL eran correctos, pero el **texto plano se había construido como una cadena de consulta** (`sid=...&authUserId=...`). La URL no redirigió a la página de error `PV-40015` — permaneció en `/face-auth` y mostró "Página no encontrada". Al cambiar el texto plano a una cadena JSON funcionó correctamente.

  Si la pantalla de verificación no aparece, revise en este orden.

  1. **Formato del texto plano** — lo que se cifra es una **cadena JSON** (por ejemplo `{"sid":"..."}`). Si cifra pares `key=value` unidos con `&`, el descifrado funciona pero no se obtiene ningún `sid`.
  2. **Codificación de URL** — un `+` del resultado Base64 se interpreta como espacio en la URL, por lo que falla el propio descifrado. Aplique `encodeURIComponent`.
  3. **Estado del `sid`** — confirme que el envío eKYC referenciado está en estado `approved`.

  Los ejemplos detallados están en [Comenzar con FaceAuth — QueryString para acceder a FaceAuth](/es/idcheck/add-on/faceauth-overview#querystring-para-acceder-a-faceauth).
</Note>

### 2-2. Fallos de validación de token

Si la expiración de token está habilitada en el proyecto FaceAuth, un fallo de validación de `token` redirige a una página de error `TK-`. Para los códigos (`TK-10000` – `TK-10004`) y sus mensajes, consulte la sección de páginas de error de token en [Códigos de error y páginas de error](/es/idcheck/reference_tables/Error-codes-and-pages).

<Note>
  El `token` de FaceAuth funciona **de forma independiente del token de modo privado y del token preregistrado del proyecto principal (ID Check)** — usa su propia DB de tokens y su propio pipeline de expiración. Para su comportamiento consulte [Comenzar con FaceAuth — Definición de parámetros de solicitud](/es/idcheck/add-on/faceauth-overview#definición-de-parámetros-de-solicitud), y para la configuración en el dashboard consulte [Guía de FACE AUTH — Configuración de condiciones de expiración de Token](/dashboard/es/face-auth-guide#configuración-de-condiciones-de-expiración-de-token).
</Note>

## 3. Errores de servidor en la etapa de precarga

Errores de servidor que surgen al recuperar las opciones del proyecto y el submission referenciado. Todos son códigos `SE-`, y al usuario se le indica reintentar.

| Código de error | URL                                     | Mensaje al usuario                                                                                                                                   | Condición                                                      |
| --------------- | --------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- |
| `SE-50010`      | `/error-page/faceauth-preload-error`    | "Face authentication initialization failed"<br />A server error occurred while preparing face authentication. Please try again later.                | La **primera** consulta API de precarga de datos falla.        |
| `SE-50011`      | `/error-page/faceauth-preload-error-2`  | "Face authentication initialization failed"<br />A server error occurred while loading additional face authentication data. Please try again later.  | La **segunda** consulta API de precarga de datos falla.        |
| `SE-50012`      | `/error-page/faceauth-submission-error` | "Failed to verify face authentication status"<br />An error occurred while checking the authentication submission status. Please try again later.    | La API `checkSubmission` responde pero `result` es falsy.      |
| `SE-50013`      | `/error-page/faceauth-token-error`      | "Face authentication token processing failed"<br />An error occurred while registering the authentication token. Please try again later.             | Ocurre una excepción durante la llamada API `insertToken`.     |
| `SE-50014`      | `/error-page/faceauth-project-error`    | "Unable to load face authentication project information"<br />An error occurred while fetching project data from the server. Please try again later. | La llamada API para obtener datos del proyecto FaceAuth falla. |

<Tip>
  Face Auth solo puede referenciar submissions de ID Check en estado **`approved`**. La API de precarga devuelve la validez del submission como `result: true/false`, por lo que se espera que un `sid` no aprobado se manifieste por la vía `SE-50012` (inferido del contrato de precarga). Verifique el estado KYC de `sid` antes de emitir el enlace.
</Tip>

## 4. Mensajes al usuario en la etapa de autenticación

Tras capturar la selfie, el resultado de la llamada a la API de autenticación se bifurca en dos casos.

### 4-1. El StatusCode HTTP no es 200 (procesamiento anómalo)

Todas las causas se unifican en **un único mensaje**, mostrado en formato **AlertPopup**.

| Clave de mensaje  | Mensaje al usuario                                         |
| ----------------- | ---------------------------------------------------------- |
| `SomethingsWrong` | No se pudo procesar su solicitud.<br />Inténtelo de nuevo. |

<Note>
  La cadena original contiene un carácter de nueva línea: `"No se pudo procesar su solicitud.\nInténtelo de nuevo."`

  Los códigos de error internos nunca se exponen al usuario. Diagnostique la causa desde el webhook o desde la respuesta de [GET/FaceAuth](/es/idcheck/add-on/get-faceauth).
</Note>

### 4-2. El StatusCode HTTP es 200 pero el procesamiento no fue exitoso (rechazo)

`auth_status` se devuelve como `rejected`, y el mensaje mostrado depende de `fail_code`.

| `fail_code`               | Mensaje al usuario                    | Elemento de verificación                  |
| ------------------------- | ------------------------------------- | ----------------------------------------- |
| `no_face`                 | El reconocimiento facial falló.       | Detección facial                          |
| `face_compare_underscore` | La información que envió no coincide. | Similitud facial por debajo del umbral    |
| `face_compare_fail`       | El reconocimiento facial falló.       | No se pudo realizar la comparación facial |
| `Face_Occluded_fail`      | Su rostro está cubierto.              | Oclusión facial por encima del umbral     |
| `Face_cover_fail`         | Por favor, use una mascarilla.        | EPP facial no detectado                   |
| `Head_cover_fail`         | Por favor, use un casco de seguridad. | EPP de cabeza no detectado                |
| `active_liveness_fail`    | La autenticación facial falló.        | Active Liveness por debajo del umbral     |
| `passive_liveness_fail`   | La autenticación facial falló.        | Passive Liveness por debajo del umbral    |

<Note>
  `no_face` y `face_compare_fail` comparten un mismo mensaje, igual que `active_liveness_fail` y `passive_liveness_fail`. Use `fail_code` — no el mensaje — para identificar qué verificación falló.
</Note>

<Warning>
  **Notación de códigos**

  * Los valores de `fail_code` **distinguen mayúsculas y minúsculas**. `Face_Occluded_fail`, `Face_cover_fail` y `Head_cover_fail` comienzan con mayúscula; el resto son minúsculas.
  * En Face Auth, los códigos de fallo de liveness son **`active_liveness_fail`** (Active) y **`passive_liveness_fail`** (Passive). Los valores `liveness_fail_active` y `liveness_fail` en [Códigos y comentarios de rechazo](/es/idcheck/reference_tables/reject-codes-and-comments) son códigos de reintento del proceso principal de ID Check — valores distintos.
</Warning>

<Note>
  La tabla anterior lista los **mensajes mostrados en pantalla**. Las cadenas `rejected_comment` entregadas mediante la respuesta de la API y los webhooks (por ejemplo, `face compare similarity score is lower than threshold`) son valores distintos — consulte [POST/Faceauth — Códigos de fallo](/es/idcheck/add-on/post-faceauth#6-1-códigos-de-fallo).
</Note>

### 4-3. Códigos de fallo de liveness

La verificación de liveness se ejecuta según la configuración `livenessMode` (`passive` / `active`) de la política del proyecto, y devuelve los siguientes códigos en caso de fallo.

| `fail_code`             | `rejected_comment`                    | Elemento de verificación               |
| ----------------------- | ------------------------------------- | -------------------------------------- |
| `active_liveness_fail`  | Please retry with another face image. | Active Liveness por debajo del umbral  |
| `passive_liveness_fail` | Please retry with another face image. | Passive Liveness por debajo del umbral |

<Note>
  `rejected_comment` es el valor entregado mediante la respuesta de la API y los webhooks. Ambos códigos comparten la misma cadena de comentario, así que use `fail_code` para determinar qué verificación de liveness falló.
</Note>

## 5. Política de reintentos

<Warning>
  **Face Auth no tiene reintentos.** Un solo fallo produce un rechazo inmediato y, a diferencia de ID Check y Knowledge-Based, nunca se genera el código de rechazo `too_many_retry`.

  Para una comparación con ID Document (3 reintentos) y Knowledge-Based (5 reintentos), consulte [Códigos y comentarios de rechazo — Códigos de reintento](/es/idcheck/reference_tables/reject-codes-and-comments#códigos-de-reintento).
</Warning>

## 6. Documentos relacionados

<CardGroup cols={2}>
  <Card title="Comenzar con FaceAuth" icon="link" href="/es/idcheck/add-on/faceauth-overview">
    Estructura de Face Auth URL y definiciones de parámetros QueryString
  </Card>

  <Card title="POST/Faceauth" icon="code" href="/es/idcheck/add-on/post-faceauth">
    Códigos de fallo y códigos de error del flujo API
  </Card>

  <Card title="Códigos de error y páginas de error" icon="triangle-exclamation" href="/es/idcheck/reference_tables/Error-codes-and-pages">
    Taxonomía completa de códigos de error y definiciones de páginas de error
  </Card>

  <Card title="Guía de FACE AUTH" icon="gauge" href="/dashboard/es/face-auth-guide">
    Políticas del dashboard, umbrales y configuración de expiración de token
  </Card>
</CardGroup>