Error Handling

Overview

Errors in the Seam Android SDK fall into two categories:

SeamError — Thrown by SDK operations such as initialize(), activate(), deactivate(), refresh(), and unlock(). These represent SDK setup, configuration, or API-level failures.
SeamCredentialError — Stored in SeamCredential.errors. These represent issues with a specific credential that must be resolved before it can be used for an unlock.

Handling both types ensures your app can present clear, actionable guidance to users.

SeamError

SeamError is a sealed class. Each subtype maps to a specific failure mode:

Subtype	Thrown by	Description
`SeamError.AlreadyInitialized`	`initialize()`	The SDK is already initialized. Call `deactivate(deintegrate = true)` before re-initializing with a new token.
`SeamError.InitializationRequired`	`getInstance()`, `activate()`, `refresh()`, `unlock()`	The SDK has not been initialized; call `SeamSDK.initialize()` first.
`SeamError.InvalidClientSessionToken`	`initialize()`, `activate()`	The client session token is malformed or has expired. Obtain a fresh token from your server.
`SeamError.InternetConnectionRequired`	`initialize()`, `activate()`, `refresh()`	A network connection is required for this operation.
`SeamError.DeactivationInProgress`	`initialize()`, `refresh()`, `deactivate()`	A deactivation is already running; wait for it to complete before retrying.
`SeamError.ActivationRequired`	`unlock()`	The SDK has not been activated; call `activate()` first.
`SeamError.InvalidCredentialId`	`unlock()`	No credential matches the specified ID. Verify the credential ID against `credentials.value`.
`SeamError.IntegrationNotFound`	`unlock()`	No provider integration was found for this credential. Ensure you added the correct provider module (for example, `seam-phone-sdk-android-assaabloy`) in your Gradle dependencies.
`SeamError.CredentialErrors`	`unlock()`	The credential has unresolved errors. Inspect `e.errors` (a `List<SeamCredentialError>`) and resolve them before retrying the unlock.
`SeamError.InvalidUnlockProximity`	`unlock()`	The specified `UnlockProximity` is not supported by this credential.

Handling SeamError in code

try {
    SeamSDK.getInstance().activate()
} catch (e: SeamError) {
    when (e) {
        is SeamError.InitializationRequired     -> showError("SDK not initialized. Please restart the app.")
        is SeamError.InternetConnectionRequired -> showError("No internet connection.")
        is SeamError.InvalidClientSessionToken  -> promptReSignIn()
        is SeamError.DeactivationInProgress     -> { /* Retry after a short delay */ }
        else                                    -> showError("Unexpected error: ${e.message}")
    }
}

SeamCredentialError

SeamCredentialError is a sealed class stored in SeamCredential.errors. A credential may have zero or more errors simultaneously. Check errors before calling unlock():

Subtype	Description
`SeamCredentialError.Loading`	The credential is still being provisioned. Wait for the `credentials` StateFlow to emit an updated list where this error is no longer present.
`SeamCredentialError.Expired`	The credential has expired. Contact the credential issuer or administrator to reissue it.
`SeamCredentialError.UserInteractionRequired(interaction)`	The user must take a specific action before this credential can be used. Inspect the `interaction` property.
`SeamCredentialError.Unknown`	An unclassified error occurred. Retry or contact Seam support.

Checking credential errors before unlock

val credential = SeamSDK.getInstance().credentials.value
    .firstOrNull { it.id == targetCredentialId }
    ?: return showError("Credential not found")

if (credential.errors.isNotEmpty()) {
    credential.errors.forEach { error ->
        when (error) {
            is SeamCredentialError.Loading -> {
                showStatus("Credential is loading, please wait...")
            }
            is SeamCredentialError.Expired -> {
                showError("This credential has expired. Contact your administrator.")
            }
            is SeamCredentialError.UserInteractionRequired -> {
                handleUserInteraction(error.interaction)
            }
            is SeamCredentialError.Unknown -> {
                showError("An unexpected error occurred. Please try again.")
            }
        }
    }
} else {
    // Credential is ready — proceed with unlock
    val credentialId = credential.id ?: return showError("Credential has no ID.")
    performUnlock(credentialId)
}

SeamRequiredUserInteraction

When a credential has a SeamCredentialError.UserInteractionRequired error, the interaction property tells you exactly what the user needs to do:

Subtype	Description	Recommended Action
`SeamRequiredUserInteraction.CompleteOtpAuthorization(otpUrl)`	The user must complete an OTP authorization flow.	Open `otpUrl` in a browser or WebView.
`SeamRequiredUserInteraction.EnableInternet`	The device has no internet connection.	Prompt the user to enable Wi-Fi or mobile data.
`SeamRequiredUserInteraction.EnableBluetooth`	Bluetooth is disabled.	Prompt the user to enable Bluetooth in Settings or the quick settings panel.
`SeamRequiredUserInteraction.GrantPermissions(permissions)`	One or more Android permissions have not been granted.	Use `ActivityCompat.requestPermissions()` with the list of permission strings in `permissions`.

Handling required user interactions

fun handleUserInteraction(interaction: SeamRequiredUserInteraction) {
    when (interaction) {
        is SeamRequiredUserInteraction.CompleteOtpAuthorization -> {
            // Open the OTP URL so the user can complete authorization
            openUrl(interaction.otpUrl)
        }
        is SeamRequiredUserInteraction.EnableInternet -> {
            showMessage("Please enable your internet connection and try again.")
        }
        is SeamRequiredUserInteraction.EnableBluetooth -> {
            showMessage("Please enable Bluetooth and try again.")
            // Optionally launch the Bluetooth settings screen:
            // startActivity(Intent(Settings.ACTION_BLUETOOTH_SETTINGS))
        }
        is SeamRequiredUserInteraction.GrantPermissions -> {
            // Request the missing permissions
            ActivityCompat.requestPermissions(
                activity,
                interaction.permissions.toTypedArray(),
                REQUEST_CODE_SEAM_PERMISSIONS
            )
        }
    }
}

Handling unlock errors end-to-end

The following example shows a complete unlock handler that covers both pre-flight credential checks and runtime SeamError cases:

fun performUnlock(credentialId: String) {
    coroutineScope.launch {
        val seam = SeamSDK.getInstance()

        // Check credential errors before attempting unlock
        val credential = seam.credentials.value.firstOrNull { it.id == credentialId }
        if (credential == null) {
            showError("Credential not found.")
            return@launch
        }
        if (credential.errors.isNotEmpty()) {
            // Show the first blocking error to the user
            val firstError = credential.errors.first()
            when (firstError) {
                is SeamCredentialError.Loading                -> showStatus("Loading...")
                is SeamCredentialError.Expired                -> showError("Credential expired.")
                is SeamCredentialError.UserInteractionRequired -> handleUserInteraction(firstError.interaction)
                is SeamCredentialError.Unknown                -> showError("Unknown credential error.")
            }
            return@launch
        }

        // Collect unlock events before initiating the unlock
        launch {
            seam.unlockStatus.collect { event ->
                when (event) {
                    is SeamUnlockEvent.ScanningStarted -> showStatus("Scanning...")
                    is SeamUnlockEvent.AccessGranted   -> showSuccess("Access granted!")
                    is SeamUnlockEvent.Timeout         -> showError("Operation timed out.")
                    is SeamUnlockEvent.ReaderError     -> showError("Reader error: ${event.message}")
                }
            }
        }

        // Initiate the unlock
        try {
            seam.unlock(credentialId = credentialId, timeout = 30.seconds)
        } catch (e: SeamError) {
            when (e) {
                is SeamError.ActivationRequired  -> showError("Please activate the SDK first.")
                is SeamError.InvalidCredentialId -> showError("Credential not found.")
                is SeamError.IntegrationNotFound -> showError("Provider not installed.")
                is SeamError.CredentialErrors    -> {
                    // Errors surfaced at unlock time — re-run the credential check above
                    e.errors.firstOrNull()?.let { handleCredentialError(it) }
                }
                else -> showError("Unlock failed: ${e.message}")
            }
        }
    }
}

Best Practices

Check credential.errors before calling unlock() — An unlock attempt on a credential with unresolved errors will throw SeamError.CredentialErrors. Checking upfront lets you present better UX before the call.
Subscribe to unlockStatus before unlock() — unlock() emits events immediately; subscribing after the call can miss early events like ScanningStarted.
Map errors to UI states — Distinguish loading states (SeamCredentialError.Loading) from actionable errors so you show spinners rather than error messages while credentials are provisioning.
Retry transient errors — SeamError.InternetConnectionRequired and SeamError.DeactivationInProgress are transient. Implement retry logic with backoff for these cases.

Overview

iOS SDK

Android SDK

Error Handling

Overview

SeamError

Handling SeamError in code

SeamCredentialError

Checking credential errors before unlock

SeamRequiredUserInteraction

Handling required user interactions

Handling unlock errors end-to-end

Best Practices

See Also

​Overview

​SeamError

​Handling SeamError in code

​SeamCredentialError

​Checking credential errors before unlock

​SeamRequiredUserInteraction

​Handling required user interactions

​Handling unlock errors end-to-end

​Best Practices

​See Also

Overview

SeamError

Handling SeamError in code

SeamCredentialError

Checking credential errors before unlock

SeamRequiredUserInteraction

Handling required user interactions

Handling unlock errors end-to-end

Best Practices

See Also