Manejo de errores en Disclosure

Manejo de errores en Disclosure

Esta guía te ayuda a entender y manejar los diferentes tipos de errores que pueden ocurrir durante el proceso de disclosure y validación de identidad.

Eventos de error en webhooks

Durante el proceso de disclosure, si ocurre un error, se enviarán varios eventos mediante webhooks que representan errores en el estado del proceso y sus objetos asociados.

Configuración de webhooks

Para recibir estos eventos de error, necesitas configurar un webhook en tu cuenta. Revisa nuestra guía completa de webhooks para aprender a configurar y verificar los webhooks correctamente.

Errores de disclosure

Los eventos de error principales que puedes escuchar son:

• disclosure_request.timed_out: El usuario no completa el disclosure en el tiempo permitido
• disclosure_request.failed: El disclosure falla por alguna razón de la que no se puede recuperar

Disclosure request caducado

{
    id: "evt_...",
    name: "disclosure_request.timed_out",
    payload: {
        user_reference: "<user-reference>",
        disclosure_request_id: "dreq_...",
    },
    created_at: "<created_at>"
}

Disclosure request fallido (error en el match)

{
    id: "evt_...",
    name: "disclosure_request.failed",
    payload: {
        user_reference: "<user-reference>",
        disclosure_request_id: "dreq_...",
    },
}

Errores de validación y autenticación

Durante el proceso de verificación de identidad, se pueden producir errores que se comunican mediante webhooks. Estos eventos incluyen información detallada sobre fallos en la verificación, como problemas de autenticación o validación de datos de identidad.

Errores de Validación

• validation_attempt.failed: La validación de identidad falló, pero puede recuperarse

Validación fallida

{
    id: "evt_...",
    name: "validation_attempt.failed",
    payload: {
        user_reference: "<user-reference>",
        validation_attempt_id: "va_...",
        error_reason: "facial_validation_error",
        errors_array: [
        {
            code: "auth-001",
            type: "facial",
            message: "facial_validation_error",
            detail: "No pudimos asegurar la prueba de vida del usuario"
        },
        ...
        ]
    },
    created_at: "<created_at>"
}

Errores de Autenticación

• auth_attempt.failed: La autenticación falló, pero puede recuperarse

Autenticación fallida

{
    id: "evt_...",
    name: "auth_attempt.failed",
    payload: {
        user_reference: "<user-reference>",
        auth_attempt_id: "aa_...",
        error_reason: "facial_validation_error",
        errors_array: [
        {
            code: "auth-001",
            type: "facial",
            message: "facial_validation_error",
            detail: "No pudimos asegurar la prueba de vida del usuario"
        },
        ...
        ]
    },
    created_at: "<created_at>"
}

Códigos de error de validación

Para las validaciones fallidas, los errores que puedes recibir se encuentran en dos campos:

• error_reason: Contiene el primer error detectado durante el proceso
• errors_array: Contiene todos los errores detallados detectados durante el proceso, con información específica sobre cada uno

Cada objeto en el errors_array incluye:

• code: Código asociado al error (ej. auth-001)
• type: Tipo de validación que falló (facial, document u other)
• message: Categoría funcional del error
• detail: Descripción específica del motivo del fallo

Interpreta el error completo

Los códigos auth-XXX no tienen un significado global. Distintos motores de validación pueden reutilizar el mismo code con otros valores de type y message. Maneja cada error con la combinación de code, type, message y detail, no solo con code.

Tabla de códigos seleccionados

Esta tabla muestra los mapeos actuales de los códigos incluidos para la validación de identidad disponible y la validación con bases de datos gubernamentales. No es el catálogo completo de códigos auth-XXX. Un mismo errors_array puede combinar ambos orígenes, por lo que algunos códigos aparecen con más de un significado.

origen	code	type	message	detail
Identidad	auth-000	other	unknown_facetec_error	Hubo un error inesperado.
Identidad	auth-001	facial	facial_validation_error	No pudimos asegurar la prueba de vida del usuario.
Identidad	auth-003	document	document_has_expired	El documento ya no es válido, ya que la fecha de expiración ha sido superada.
Identidad	auth-008	document	document_not_recognized	El documento no fue reconocido como una versión válida para el país.
Identidad	auth-015	document	document_validation_error	La información en el campo MRZ no coincide con la información en los otros campos del documento.
Identidad	auth-036	document	photo_of_photo	No se pudo confirmar la identidad del usuario. El usuario debe reintentar.
Identidad	auth-036	document	document_validation_error	No pudimos detectar el documento completo.
Identidad	auth-047	document	facial_validation_error	Hubo un error validando el documento de video facial.
Identidad	auth-047	document	facial_validation_error	Hubo un error validando el rostro en el documento.
Identidad	auth-048	document	image_validation_not_passed	El análisis de la foto del documento no pasó la validación.
Identidad	auth-048	document	image_validation_not_passed	La validación de la foto del documento no fue superada.
Identidad	auth-048	document	image_validation_not_passed	No pudimos detectar claramente el rostro en el documento.
Identidad	auth-053	document	document_validation_error	Rut inválido o extraído incorrectamente.
Identidad	auth-053	document	document_validation_error	No pudimos leer correctamente la nacionalidad del documento.
Identidad	auth-065	document	possible_fraud	No se pudo confirmar que el documento sea real. El usuario debe reintentar.
Identidad	auth-070	facial	facial_validation_error	La verificación del registro de auditoría falló.
Identidad	auth-071	facial	facial_validation_error	La verificación de la regrabación de la prueba de vida falló.
Identidad	auth-072	document	document_validation_error	No pudimos verificar el sello de agua ni el holograma del documento.
Identidad	auth-073	document	document_sides_mismatch	No pudimos confirmar que la parte frontal y trasera pertenecen al mismo documento.
Identidad	auth-074	document	nfc_validation_failed	La lectura del chip NFC del documento no fue exitosa.
Identidad	auth-075	document	nfc_not_supported_by_device	El dispositivo no soporta lectura NFC.
Identidad	auth-077	document	nfc_identity_mismatch	No pudimos confirmar que la identidad del chip NFC coincida con la biometría.
Base de datos gubernamental	auth-003	other	expiration_error	La validación expiró antes de que terminara la verificación gubernamental.
Base de datos gubernamental	auth-074	document	invalid_document_number	Número de documento inválido.
Base de datos gubernamental	auth-075	document	government_api_error	No se pudo verificar la base de datos gubernamental porque no estaba disponible en el momento de la consulta.
Base de datos gubernamental	auth-076	document	document_not_valid	El documento no se encuentra vigente.

En los errores de identidad, auth-074 y auth-075 corresponden a fallas técnicas de la validación NFC y aparecen cuando mobile_nfc_strictness es flexible_on_unsupported o strict. auth-077 identifica una discrepancia entre la identidad del chip y la biometría; bloquea el intento y no debe ofrecer reintento.

auth-065 agrupa decisiones de posible fraude. Puede originarse por una señal de spoof, una incompatibilidad de edad, medios inesperados o actividad repetida. La primera incompatibilidad de edad o señal de medios inesperados permite reintentar. Una señal repetida o una decisión de velocidad termina el disclosure.

Cuántos reintentos permite auth-065 depende del nivel de control de riesgo de la plantilla: con strict la primera señal termina el disclosure sin reintento, y con monitor no se emite auth-065 en absoluto porque las señales solo se registran.

Los message que pueden aparecer en otros motores de validación son:

Errores de validación de identidad

• unknown: Error desconocido

Errores de documento

• document_validation_error: Error en la validación del documento
• document_has_expired: El documento expiró
• document_not_recognized: El documento no fue reconocido
• document_sides_mismatch: Los datos de la parte frontal y del reverso del documento no coinciden
• document_unregistered: El documento no está registrado
• damaged_document: El documento está dañado
• document_is_a_photo_of_photo: Error en la imagen
• document_is_a_photocopy: El documento es una copia
• incomplete_document: El documento es incompleto
• invalid_issue_date: La fecha de emisión es inválida
• missing_date_of_birth: Falta la fecha de nacimiento
• missing_document_number: Falta el número del documento
• missing_expiration_date: Falta la fecha de expiración
• missing_gender: Falta el género
• missing_mrz: Falta el MRZ
• missing_names: Falta los nombres
• missing_text: Falta el texto
• missing_issue_date: Falta la fecha de emisión
• missing_nationality: Falta la nacionalidad

Errores de imagen

• blurry_image: La imagen es borrosa
• front_document_not_found: No se encontró la imagen frontal del documento
• invalid_or_corrupted_image_file: La imagen es inválida o está corrupta
• photo_of_photo: La imagen es de una foto de una foto
• reverse_document_not_found: No se encontró la imagen inversa
• image_validation_not_passed: No pasó la validación de la imagen

Errores de validación facial

• facial_validation_error: Error en la validación facial
• fraudster_face_match_in_client_collection: La coincidencia de rostro es de un fraude
• liveness_verification_not_passed: La verificación de vivacidad no fue exitosa
• no_face_detected: No se detectó rostro
• passive_liveness_verification_not_passed: La verificación de vivacidad pasiva no fue exitosa
• similarity_threshold_not_passed: No pasó el umbral de similitud
• face_not_clear: El rostro no es claro
• face_not_detected: No se detectó rostro

Errores de validación con base de datos gubernamental

• data_not_match_with_government_database: Los datos no coinciden con la base de datos del gobierno
• government_database_unavailable: La base de datos del gobierno no está disponible
• identity_belongs_to_dead_person: La identidad del usuario pertenece a una persona fallecida

Errores de edad

• age_above_threshold: El usuario es mayor a la edad máxima permitida
• underage: El usuario es menor de edad

Errores técnicos

• ocr_no_text_detected: No se detectó texto
• expiration_error: La validación expiró
• enrollment: El usuario falló al inscribirse
• camera_permission_error: No se tiene permiso para usar la cámara
• invalid_format: El formato es inválido
• possible_fraud: Es posible que sea fraude
• validations_failed: Error en las validaciones

Próximos pasos

• Revisa la guía de webhooks para configurar correctamente el manejo de eventos
• Consulta la configuración del módulo de Disclosure para opciones de personalización
• Explora la guía de validación de identidad para el flujo completo de integración