Skip to main content

​
Acuant Error Codes

The Acuant module provides advanced document capture and verification capabilities. When errors occur, they are thrown as ResponseError objects with specific error codes.

​
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
}

​
Error Codes

​
UNSUPPORTED_CAMERA

Thrown when the device camera is not supported or compatible with the Acuant SDK. Code: FadSDK.Errors.Acuant.UNSUPPORTED_CAMERA When it occurs:
  • Device doesn’t have a compatible camera
  • Browser doesn’t support required camera APIs
  • Camera hardware is incompatible with Acuant requirements
  • Mobile device camera lacks necessary features
How to handle: 
try {
  const moduleResponse = await FAD_SDK.startAcuant(
    CREDENTIALS,
    idData,
    idPhoto,
    manualCapture,
    CONFIGURATION
  );
} catch (ex) {
  if (ex.code === FadSDK.Errors.Acuant.UNSUPPORTED_CAMERA) {
    alert('Camera not supported. Please try on a different device.');
    // Redirect to alternative capture method or device
  }
}
This is a critical error that typically cannot be resolved without changing devices. Consider providing alternative document capture methods.

​
FAIL_INITIALIZATION

Thrown when the Acuant SDK fails to initialize properly. Code: FadSDK.Errors.Acuant.FAIL_INITIALIZATION When it occurs:
  • Invalid or expired credentials
  • Network connection issues during initialization
  • Acuant service is unavailable
  • Configuration errors
How to handle: 
try {
  const moduleResponse = await FAD_SDK.startAcuant(
    CREDENTIALS,
    idData,
    idPhoto,
    manualCapture,
    CONFIGURATION
  );
} catch (ex) {
  if (ex.code === FadSDK.Errors.Acuant.FAIL_INITIALIZATION) {
    console.error('Acuant initialization failed:', ex);
    // Retry initialization or check credentials
    alert('Initialization failed. Please check your connection and try again.');
  }
}
Verify your credentials and network connectivity when this error occurs. It may also indicate service maintenance.

​
FAIL_GET_OCR

Thrown when OCR (Optical Character Recognition) extraction from the document fails. Code: FadSDK.Errors.Acuant.FAIL_GET_OCR When it occurs:
  • Document quality is insufficient for OCR processing
  • OCR service encountered an error
  • Network timeout during OCR processing
  • Document type doesn’t support OCR extraction
How to handle: 
try {
  const moduleResponse = await FAD_SDK.startAcuant(
    CREDENTIALS,
    true,  // idData - requesting OCR
    idPhoto,
    manualCapture,
    CONFIGURATION
  );
  
  console.log(moduleResponse.data.idData.ocr);
} catch (ex) {
  if (ex.code === FadSDK.Errors.Acuant.FAIL_GET_OCR) {
    alert('Failed to extract text from document. Please retry with better image quality.');
    // Restart capture process
  }
}

​
FAIL_GET_FACE_IMAGE

Thrown when the face image extraction process fails. Code: FadSDK.Errors.Acuant.FAIL_GET_FACE_IMAGE When it occurs:
  • Face detection service error
  • Network issues during face extraction
  • Processing timeout
  • Invalid document format for face extraction
How to handle: 
try {
  const moduleResponse = await FAD_SDK.startAcuant(
    CREDENTIALS,
    idData,
    true,  // idPhoto - requesting face extraction
    manualCapture,
    CONFIGURATION
  );
} catch (ex) {
  if (ex.code === FadSDK.Errors.Acuant.FAIL_GET_FACE_IMAGE) {
    console.error('Face extraction failed:', ex);
    alert('Failed to extract face image. Please try again.');
    // Retry or provide alternative
  }
}

​
FACE_IMAGE_URL_NOT_FOUND

Thrown when the URL for the face image is not found in the response. Code: FadSDK.Errors.Acuant.FACE_IMAGE_URL_NOT_FOUND When it occurs:
  • Acuant service didn’t return face image URL
  • Response parsing error
  • Service configuration issue
  • Document doesn’t contain a face photo
How to handle: 
try {
  const moduleResponse = await FAD_SDK.startAcuant(
    CREDENTIALS,
    idData,
    true,
    manualCapture,
    CONFIGURATION
  );
} catch (ex) {
  if (ex.code === FadSDK.Errors.Acuant.FACE_IMAGE_URL_NOT_FOUND) {
    console.error('Face image URL not found');
    // Handle missing URL - may need to retry or skip face photo
  }
}

​
FACE_IMAGE_NOT_FOUND

Thrown when no face image can be detected or extracted from the document. Code: FadSDK.Errors.Acuant.FACE_IMAGE_NOT_FOUND When it occurs:
  • Document doesn’t have a visible face photo
  • Face photo area is obscured or damaged
  • Image quality too poor for face detection
  • Wrong document side captured (back instead of front)
How to handle: 
try {
  const moduleResponse = await FAD_SDK.startAcuant(
    CREDENTIALS,
    idData,
    true,
    manualCapture,
    CONFIGURATION
  );
} catch (ex) {
  if (ex.code === FadSDK.Errors.Acuant.FACE_IMAGE_NOT_FOUND) {
    alert('No face photo found on document. Please ensure you capture the front side.');
    // Restart capture with guidance
  }
}

​
Complete Error Handling Example

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

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

  try {
    const idData = true;
    const idPhoto = true;
    const manualCapture = true;

    const moduleResponse = await FAD_SDK.startAcuant(
      CREDENTIALS,
      idData,
      idPhoto,
      manualCapture,
      CONFIGURATION
    );

    // Process successful response
    console.log('Document captured successfully');
    const imageIdFront = moduleResponse.data.id.front.image.data;
    const imageIdBack = moduleResponse.data.id?.back?.image?.data;
    const imageFace = moduleResponse.data.idPhoto;
    const ocr = moduleResponse.data.idData.ocr;

    console.log('Front image:', imageIdFront);
    console.log('Back image:', imageIdBack);
    console.log('Face photo:', imageFace);
    console.log('OCR data:', ocr);

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

    // Handle specific errors
    if (ex.code === FadSDK.Errors.Acuant.UNSUPPORTED_CAMERA) {
      alert('Camera not supported. Please try on another device.');
    } else if (ex.code === FadSDK.Errors.Acuant.FAIL_INITIALIZATION) {
      alert('Failed to initialize. Please check your connection.');
      // Retry logic
    } else if (ex.code === FadSDK.Errors.Acuant.FAIL_GET_OCR) {
      alert('Failed to read document text. Please try again.');
      // Restart capture
    } else if (ex.code === FadSDK.Errors.Acuant.FAIL_GET_FACE_IMAGE) {
      alert('Failed to extract face image. Please try again.');
      // Restart capture
    } else if (ex.code === FadSDK.Errors.Acuant.FACE_IMAGE_URL_NOT_FOUND) {
      console.error('Face image URL not found');
      // Handle missing URL
    } else if (ex.code === FadSDK.Errors.Acuant.FACE_IMAGE_NOT_FOUND) {
      alert('No face photo found. Please capture the front of the ID.');
      // Restart capture
    } else {
      alert(`Unexpected error: ${ex.message}`);
    }
  } finally {
    FAD_SDK.end();
  }
}

​
Error Recovery Strategies

For UNSUPPORTED_CAMERA, provide fallback options:
  • Manual document upload
  • Alternative device guidance
  • Desktop/mobile switching recommendation
For face/OCR extraction failures, provide real-time feedback:
  • Show capture quality indicators
  • Guide users to improve lighting
  • Display document positioning helpers

​
Best Practices

Pre-flight Checks

Verify camera support and permissions before calling startAcuant() to provide better user experience.

Graceful Degradation

When face image extraction fails, consider whether you can proceed without it based on your use case.

User Feedback

Provide clear, actionable error messages to users. Avoid exposing technical error codes in the UI.

Build docs developers (and LLMs) love

Get started for freeTalk to us