Handling errors

Most problems during a scan are ones the user can fix or the SDK recovers from on its own. Your app only needs to step in when a scan has stopped, and even then, the error tells you whether trying again is worth it.

Every failure is a RoomioError. You'll meet one in two places:

a call throws, such as startScan, stop or export
session.state becomes failed, which means the scan has stopped

Two questions, not a list of codes

Rather than matching every error code, ask two questions of each error. That keeps your app working when future releases add new codes.

Has the scan stopped? severity tells you. A recoverable error means the scan carries on, and the scan view is already telling the user what to do. A fatal error means the scan is over.

Is it worth trying again? isRetryable tells you. A camera another app was using might be free now; a phone that can't scan never will be.

Severity	What it means	What to do
Recoverable	The scan continues.	Nothing, or show a hint of your own.
Fatal	The scan has stopped.	Close the session. If `isRetryable` is true, offer a new scan.

if error.severity == .fatal {
    session.close()
    showMessage(error.message, canRetry: error.isRetryable)
}

if (error.severity == RoomioError.Severity.FATAL) {
    session.close()
    showMessage(error.message, canRetry = error.isRetryable)
}

if (error.severity === 'fatal') {
  session.close();
  showMessage(error.message, { canRetry: error.isRetryable });
}

In JavaScript, a failed call rejects with an Error carrying code, message, severity and isRetryable, and a failed scan sets state to { type: 'failed', error } with the same fields.

When a fatal error ends a scan that was recording, RoomioScanView also tells the user: "Something went wrong" with Go back, which only closes the dialog. Your own message can follow once it's gone, or you can skip it, since the user has already been told. When saving after stop(), or export(), fails, the view shows "Couldn't save the scan" the same way; a retryable export_failed can still be retried behind it. Hide your own controls while session.isShowingDialog is true, so nothing can be tapped behind a dialog.

On Android the view also explains two ARCore problems in the same kind of dialog. On a device ARCore doesn't support, it shows "Device not supported" with Go back alongside the device_not_supported error. When Google Play Services for AR is missing, out of date or its install was declined before the scan starts, it shows "Install AR services" with Install, which opens Play's install prompt again; the scan isn't failed, and a start you made carries on once the package is installed.

There's one exception: export_failed. The scan itself is safe, so if isRetryable is true, call export() again rather than asking the user to scan again.

When to look at the code

Check code when you want to say something specific to the user, such as sending them to Settings when they've declined the camera.

Code	What happened	What to do
`not_configured`	`startScan` was called before `configure`.	Call `configure` at launch.
`device_not_supported`	This device can't scan.	Hide the scan option.
`connection_required`	The app hasn't been online since it was installed or updated. The first scan after either needs a connection; after that, scanning works offline.	Ask the user to connect, then try again.
`publishable_key_rejected`	Roomio didn't accept your publishable key, and the app has no settings from before.	Fix the key passed to `configure`. See Troubleshooting.
`sdk_update_required`	Roomio no longer supports this version of the SDK.	Ask the user to update your app, and ship an update with the latest SDK.
`permission_denied`	The user declined camera access. On iOS, also when `NSCameraUsageDescription` is missing.	Usually nothing: the scan view asks the user to allow access in Settings, and the scan carries on once they do. If it's fatal (iOS, `NSCameraUsageDescription` missing), add the key.
`session_unavailable`	The camera couldn't start, for example because another app is using it.	If retryable, ask the user to try again.
`capture_failed`	Something went wrong while recording.	If fatal, offer a new scan.
`not_ready`	`stop()` was called in the first few seconds of a scan.	Call `stop()` again a little later.
`power_saving`	`start()` was called while Low Power Mode (iOS) or Battery Saver (Android) is on, so the scan didn't start. The scan view shows a sheet, and closing it cancels the session.	Start a new scan once it's off.
`insufficient_storage`	`start()` was called with under 200 MB of free storage, so the scan didn't start. The scan view shows a sheet, and closing it cancels the session.	Ask the user to free space, then start a new scan.
`low_battery`	`start()` was called with the battery at 25% or less, so the scan didn't start. The scan view shows a sheet, and closing it cancels the session.	Start a new scan once the device has charged.
`export_failed`	The finished scan couldn't be packaged.	If retryable, call `export()` again.

Each code's entry in the iOS and Android reference has more detail. If an error looks like a bug in the SDK, send Roomio a diagnostics file.

Export and upload

Diagnostics