Esta página cubre los fallos del flujo A. Face Auth URL (consulte Comenzar con FaceAuth).Para los códigos de fallo y códigos de error del flujo B. API POST /faceauth, consulte POST/Faceauth. Los dos flujos usan pipelines de verificación distintos, por lo que los códigos devueltos y el manejo de fallos también difieren.
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.1
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 entrada2
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
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
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 llevepid no inicia la verificación; la forma mínima ejecutable requiere el sid de referencia, cifrado y enviado dentro de encrypted.
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.- Formato del texto plano — lo que se cifra es una cadena JSON (por ejemplo
{"sid":"..."}). Si cifra pareskey=valueunidos con&, el descifrado funciona pero no se obtiene ningúnsid. - Codificación de URL — un
+del resultado Base64 se interpreta como espacio en la URL, por lo que falla el propio descifrado. ApliqueencodeURIComponent. - Estado del
sid— confirme que el envío eKYC referenciado está en estadoapproved.
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 detoken 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.
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, y para la configuración en el dashboard consulte Guía de FACE AUTH — Configuración de condiciones de expiración de Token.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ódigosSE-, y al usuario se le indica reintentar.
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.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.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.
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ó.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.4-3. Códigos de fallo de liveness
La verificación de liveness se ejecuta según la configuraciónlivenessMode (passive / active) de la política del proyecto, y devuelve los siguientes códigos en caso de fallo.
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ó.5. Política de reintentos
6. Documentos relacionados
Comenzar con FaceAuth
Estructura de Face Auth URL y definiciones de parámetros QueryString
POST/Faceauth
Códigos de fallo y códigos de error del flujo API
Códigos de error y páginas de error
Taxonomía completa de códigos de error y definiciones de páginas de error
Guía de FACE AUTH
Políticas del dashboard, umbrales y configuración de expiración de token