Skip to main content

​
Facetec Error Codes

The Facetec module provides 3D liveness detection and face scanning capabilities. Errors are organized into categories based on the phase where they occur.

​
Error Structure

All errors follow the ResponseError structure: 
interface ResponseError {
  code: string;        // Error code constant
  message: string;     // Human-readable error message
  details?: any;       // Optional additional error details
}

​
Session Errors

Errors that occur during the Facetec session initialization and camera setup.

​
Session.CAMERA_NOT_RUNNING

Thrown when the camera fails to start or stops unexpectedly during the session. Code: FadSDK.Errors.Facetec.Session.CAMERA_NOT_RUNNING When it occurs:
  • Camera permission denied by user
  • Camera is in use by another application
  • Camera hardware failure
  • Browser doesn’t support camera access
  • Mobile device has disabled camera access
How to handle: 
try {
  const facetecResponse = await FAD_SDK.startFacetec(
    CREDENTIALS,
    CONFIGURATION
  );
  
  console.log(facetecResponse.data.auditTrail);
  console.log(facetecResponse.data.faceScan);
} catch (ex) {
  if (ex.code === FadSDK.Errors.Facetec.Session.CAMERA_NOT_RUNNING) {
    alert('Camera not supported or not accessible. Please check permissions and try on another device.');
    // Redirect to troubleshooting or alternative method
  }
}
This is a critical error that prevents the liveness check from proceeding. Always verify camera permissions before starting Facetec.

​
Session.INITIALIZATION_NOT_COMPLETED

Thrown when Facetec SDK initialization fails to complete successfully. Code: FadSDK.Errors.Facetec.Session.INITIALIZATION_NOT_COMPLETED When it occurs:
  • Network timeout during SDK initialization
  • Invalid or expired Facetec credentials
  • Facetec service unavailable
  • Browser compatibility issues
  • WebAssembly not supported
How to handle: 
try {
  const facetecResponse = await FAD_SDK.startFacetec(
    CREDENTIALS,
    CONFIGURATION
  );
} catch (ex) {
  if (ex.code === FadSDK.Errors.Facetec.Session.INITIALIZATION_NOT_COMPLETED) {
    console.error('Facetec initialization failed:', ex);
    alert('Failed to initialize face verification. Please check your connection and try again.');
    // Retry initialization
  }
}
Check your network connection and verify that your Facetec credentials are valid when this error occurs.

​
Status Errors

Errors related to the liveness detection process status and completion.

​
Status.TIMEOUT

Thrown when the liveness detection process exceeds the maximum allowed time. Code: FadSDK.Errors.Facetec.Status.TIMEOUT When it occurs:
  • User takes too long to complete the liveness check
  • Network latency causes processing delays
  • Poor device performance slows down face detection
  • User doesn’t follow on-screen instructions
How to handle: 
try {
  const facetecResponse = await FAD_SDK.startFacetec(
    CREDENTIALS,
    CONFIGURATION
  );
} catch (ex) {
  if (ex.code === FadSDK.Errors.Facetec.Status.TIMEOUT) {
    alert('Verification timed out. Please try again and follow the on-screen instructions.');
    // Restart the liveness check
  }
}
Consider adjusting timeout settings in your configuration if users frequently experience this error.

​
Complete Error Handling Example

import FadSDK from '@fad-producto/fad-sdk';

async function performLivenessCheck() {
  const FAD_SDK = new FadSDK(TOKEN, {
    environment: FadSDK.getFadEnvironments().UATHA
  });

  try {
    const facetecResponse = await FAD_SDK.startFacetec(
      CREDENTIALS,
      CONFIGURATION
    );

    // Process successful response
    console.log('Liveness check completed');
    
    // Access the audit trail images
    const auditImages = facetecResponse.data.auditTrail;
    const lowQualityImages = facetecResponse.data.lowQualityAuditTrail;
    const faceScan = facetecResponse.data.faceScan;

    console.log('Audit trail:', auditImages);
    console.log('Face scan:', faceScan);

    // Display results
    const highQualityImg = 'data:image/png;base64,' + auditImages[0];
    const lowQualityImg = 'data:image/png;base64,' + lowQualityImages[0];

  } catch (ex) {
    console.error('Facetec error:', ex);

    // Handle specific errors
    if (ex.code === FadSDK.Errors.Facetec.Session.CAMERA_NOT_RUNNING) {
      alert('Camera not accessible. Please enable camera permissions and try again.');
      // Provide troubleshooting steps
    } else if (ex.code === FadSDK.Errors.Facetec.Session.INITIALIZATION_NOT_COMPLETED) {
      alert('Failed to initialize face verification. Please check your connection.');
      // Retry with exponential backoff
      await retryInitialization();
    } else if (ex.code === FadSDK.Errors.Facetec.Status.TIMEOUT) {
      alert('Verification timed out. Please try again and follow the instructions carefully.');
      // Restart the process
    } else {
      console.error('Unexpected error:', ex);
      alert('An error occurred during face verification. Please try again.');
    }
  } finally {
    FAD_SDK.end();
  }
}

async function retryInitialization(maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      await performLivenessCheck();
      return; // Success
    } catch (ex) {
      if (i === maxRetries - 1) throw ex;
      // Exponential backoff
      await new Promise(resolve => setTimeout(resolve, Math.pow(2, i) * 1000));
    }
  }
}

​
Response Data Structure

When successful, Facetec returns the following data: 
interface FacetecResponse {
  data: {
    auditTrail: string[];              // Array of high-quality base64 image strings
    lowQualityAuditTrail: string[];    // Array of low-quality base64 image strings
    faceScan: string;                  // Encrypted face scan data
    sessionId?: string;                // Session identifier
  };
  event: string;                       // Event type (PROCESS_COMPLETED, MODULE_CLOSED)
}

​
Error Recovery Strategies

When CAMERA_NOT_RUNNING occurs:
  1. Check if camera permissions are granted
  2. Verify camera is not in use by another app
  3. Test camera functionality with native browser APIs
  4. Provide step-by-step permission instructions
  5. Offer alternative authentication methods
async function checkCameraPermissions() {
  try {
    const stream = await navigator.mediaDevices.getUserMedia({ video: true });
    stream.getTracks().forEach(track => track.stop());
    return true;
  } catch (ex) {
    return false;
  }
}
When INITIALIZATION_NOT_COMPLETED occurs:
  • Implement retry logic with exponential backoff
  • Verify network connectivity
  • Check Facetec service status
  • Validate credentials
  • Clear browser cache if persistent
When TIMEOUT occurs:
  • Display clear, step-by-step instructions before starting
  • Show progress indicators during the check
  • Provide countdown timer if appropriate
  • Consider increasing timeout in configuration for slow devices
  • Offer practice mode for first-time users

​
Best Practices

Pre-session Validation

Always verify camera availability and permissions before starting Facetec to avoid runtime errors.

User Experience

Show a tutorial or guide before the first liveness check to reduce timeout errors and improve success rates.

Network Resilience

Implement retry logic for initialization failures, as they’re often temporary network issues.

Device Compatibility

Test on target devices and browsers. Facetec requires WebGL and WebAssembly support.

​
Browser Requirements

Facetec requires modern browsers with:
  • WebGL support
  • WebAssembly (WASM) support
  • Camera API access
  • Minimum recommended: Chrome 80+, Safari 13+, Firefox 75+

Build docs developers (and LLMs) love

Get started for freeTalk to us