Códigos de error
Códigos de estado HTTP
| Código | Significado |
|---|---|
200 | Éxito |
400 | Solicitud incorrecta: campo obligatorio faltante o JSON malformado |
401 | No autorizado: clave API o token inválido o faltante |
403 | Prohibido: clave válida pero permisos insuficientes |
404 | No encontrado: cliente, sesión o recurso no encontrado |
429 | Demasiadas solicitudes: límite de velocidad excedido |
500 | Error interno del servidor |
Tipos de estado de sesión
Las sesiones de FaceGuard tienen un estado con etiqueta interna:
| Tipo de estado | Campos | Descripción |
|---|---|---|
in_progress | stages | Sesión activa, el usuario está en el flujo de verificación |
completed | outcome, stages, completed_at | Sesión finalizada |
bypassed | expires_at, completed_at | El cliente tiene un bypass concedido por un administrador |
Resultados completados
| Resultado | Descripción |
|---|---|
passed | El rostro coincidió con la foto base |
failed | El rostro no coincidió |
Motivos de cierre por postMessage
Eventos emitidos desde FaceGuard a la aplicación anfitriona:
| Motivo | Payload | Descripción |
|---|---|---|
approved | { confidence: number } | Cara verificada con éxito |
rejected | { confidence: number } | La cara no coincidió |
canceled | El usuario tocó X para cerrar | |
bypass_active | { bypass_expires_at: string } | El cliente tiene un bypass activo |
no_base_photo | Sin foto registrada para comparar | |
error | { error: string } | Problema de cámara, error de red, token expirado, etc. El valor de error es un código tipado — ver más abajo. |
Códigos de error de cámara
Cuando la cámara del usuario no puede iniciarse, FaceGuard emite { action: 'close', reason: 'error', error: <código> } con uno de los códigos de abajo. Puedes usar el código para mostrar una UI de recuperación específica.
| Código | Causa subyacente | Guía sugerida |
|---|---|---|
camera_permission_denied | El usuario (o el navegador / SO) denegó el acceso a la cámara (NotAllowedError) | Pide al usuario que habilite el acceso a la cámara en la configuración del sitio (web) o Ajustes → tu app (WebView móvil) |
camera_unavailable | No hay cámara en el dispositivo (NotFoundError) | Sugiere usar un dispositivo con cámara |
camera_in_use | Otra app o pestaña está usando la cámara (NotReadableError, TrackStartError) | Pide al usuario que cierre las otras apps o pestañas que la usan |
camera_constraints | Resolución / orientación pedida no soportada (OverconstrainedError) | Poco común — suele indicar una limitación de hardware |
camera_insecure_context | La página no se sirve por HTTPS, o el iframe no tiene allow="camera" (SecurityError) | Verifica que el host use HTTPS y que el iframe tenga allow="camera" |
camera_unknown | Catch-all para fallos inesperados de getUserMedia | Reintento genérico / contactar soporte |
Estados de resultado del SDK
Al usar FaceGuard.verify():
| Estado | Confianza | Error | Descripción |
|---|---|---|---|
approved | 0-100 | Cara verificada | |
rejected | 0-100 | La cara no coincidió | |
canceled | - | El usuario cerró | |
error | string | Algo salió mal. error es uno de los códigos de cámara de arriba, 'no_base_photo', u otro string. |
Puntuación de confianza
La puntuación de confianza (0-100) representa la similitud entre el rostro capturado y la foto base registrada. Puntuaciones más altas indican una coincidencia más fuerte.