Skip to main content

Handling Errors | Web Document Scanner

There are various reasons why opening a scanning screen might fail: unsupported browser, permission was denied, camera does not exist etc.

ScanbotSDK tries to attempt to handle these cases as best as possible, however, as hardware access API in the browser is not backwards compatible or future-proof, this is an ongoing challenge. In order to prevent false positives, we keep error handling to a minimum.

Promise rejections means you should try and catch when starting the scanners. If a scanner throws an error (camera permission etc.) while starting, the error can be caught as follows:

try {
    documentScanner = await scanbotSDK.createDocumentScanner(config);
} catch (error) {
    // Handle cases where scanner could not be opened
    console.log(error.name) // Console log may be  UnsupportedMediaDevicesError, MediaPermissionError, ...
}

If a scanner throws an error after being successfully started, it can be caught via onError callback in the configuration:

const config = {
    containerId: containerId,
    onError: (error) => {
        // Action taken
    },
    ...
};

Camera​

There are five types of Media Errors the SDK throws. They are defined as follows and available under:

MediaError.MESSAGE = {
    DEVICES_UNDEFINED: "MediaError_DevicesUndefined",
    ENUMERATE_FAILED: "MediaError_EnumerateFailed",
    DEVICE_NOT_FOUND: "MediaError_DeviceNotFound",
    PERMISSION_DENIED: "MediaError_PermissionDenied",
    UNKNOWN: "MediaError_Unknown"
};

If your device is missing media devices completely (e.g. desktop computer), or the browser does not support mediaDevices API, the message will be DEVICES_UNDEFINED.

Similarily, if we cannot enumerate the media devices, the message will be ENUMERATE_FAILED. This can also only happen in niche cases, e.g. unrecognized browser that do not support the mediaDevices API.

If we cannot find the camera, the message will be DEVICE_NOT_FOUND. This might be thrown if you're requesting a specific camera that does not exist. Or the native browser API cannot find a camera at all.

If your users have explicitly denied camera permission, we'll throw PERMISSION_DENIED. However, this API is somewhat experimental and we cannot guarantee that each brower and platform supports the API correctly.

If the error is none of the above, we'll throw UNKNOWN. This should never be the case.

License​

The Promise will be rejected with LicenseError when a client calls any of the Scanbot SDK functions while having a license error.

There is no internal and continuous check for invalid or expired license. You should always check this yourself via await scanbotSDK.getLicenseInfo().

Unknown​

If the encountered error is not one of the errors above and not specified in scanner specific documentation pages, it will be rejected with UnknownError.

Want to scan longer than one minute?

Generate a free trial license to test the Scanbot SDK thoroughly.

Get your free Trial License

What do you think of this documentation?

On this page

Scroll to top