Handle Errors - Kotlin SDK

On this page

Example

The Kotlin SDK uses a hierarchy of exceptions to help developers manage API call failures. There are two major categories of exceptions that your application should handle when using the Kotlin SDK:

realm errors occur when a read or write to realm database fails. These errors generate a RealmException.
app errors occur when network communication with App Services fails. These errors generate an AppException.

Some errors are ephemeral: they happen because of failures outside of the client or SDK's control. A failed login attempt due to a network error is an example of an ephemeral error.

Other errors require logic fixes. Examples include:

writing to a realm outside of a write transaction
a failed login attempt due to incorrect credentials
deleting an object that does not exist

When an ephemeral error occurs, you should retry the operation that caused the error. If the operation still fails when you retry it, investigate logic fixes.

Example

You can handle errors in the SDK with Kotlin's built-in runCatching API. Use the onSuccess and onFailure callbacks of the returned Result to handle successful SDK API calls and error cases. The following example logs an anonymous user into an App. If the login attempt succeeds, we log the successful authentication attempt and transition the user to another screen. If the login attempt fails, we handle each potential error case individually:

If the user supplied invalid credentials, we log the attempt and display a popup toast encouraging the user to check their credentials.
If there was a problem with the network connection, we log the problem to the error log and display a popup toast encouraging the user to check their network connection and try again.
For all other errors, we log the problem to the error log and display a popup toast informing the user that the login attempt failed.

val app = App.create(YOUR_APP_ID)
runCatching {
    app.login(Credentials.emailPassword(email, password))
}.onSuccess {
    Log.v("Successfully logged in")
    // transition to another activity, load a fragment, to display logged-in user information here
}.onFailure { ex: Throwable ->
    when (ex) {
        is InvalidCredentialsException -> {
            Log.v("Failed to login due to invalid credentials: ${ex.message}")
            Toast.makeText(baseContext,
                "Invalid username or password. Please try again.", Toast.LENGTH_LONG).show()
        }
        is ConnectionException -> {
            Log.e("Failed to login due to a connection error: ${ex.message}")
            Toast.makeText(baseContext,
                "Login failed due to a connection error. Check your network connection and try again.", Toast.LENGTH_LONG).show()
        }
        else -> {
            Log.e("Failed to login: ${ex.message}")
            // generic error message for niche and unknown fail cases
            Toast.makeText(baseContext,
                "Login failed. Please try again.", Toast.LENGTH_LONG).show()
        }
    }
}

← Authenticate Users - Kotlin SDK Handle Realm Errors - Kotlin SDK →