Error handling

Introduction

This topic guide describes how errors should be handled that are generated by the Onegini Android SDK. First we start with a general description on errors from
which we slowly dive deeper into the world of error handling for the Android SDK.

General description

Interaction with the Onegini SDK can result in errors. We have a pattern name for all error classes: Onegini_TYPE_Error where _TYPE_ is particular scenario
with different set of error which can occur. For example the OneginiAuthenticationHandler in its onError method returns the OneginiAuthenticationError
which specifies that only the following errors can occur:

GENERAL_ERROR,

NETWORK_CONNECTIVITY_PROBLEM,

SERVER_NOT_REACHABLE,

DEVICE_DEREGISTERED,

CONFIGURATION_ERROR,

USER_DEREGISTERED,

OUTDATED_APP,

OUTDATED_OS,

ACTION_CANCELED,

AUTHENTICATOR_NOT_REGISTERED,

INVALID_AUTHENTICATOR,

CUSTOM_AUTHENTICATOR_FAILURE,

CUSTOM_AUTHENTICATION_DISABLED,

AUTHENTICATOR_DEREGISTERED.

Apart from these error codes we will also provide you with a comprehensive error description which you can get by calling getMessage() method on
OneginiError objects. The error description is in English and intended for you as a developer to understand what happened. They are not intended for
the end-user.

OneginiError also contains an instance of OneginiErrorDetails that can be accesed by calling getErrorDetails().

/**
* An interface to return additional error details when needed.
*/publicinterfaceOneginiErrorDetails{/**
* Returns the {@link CustomInfo} object if the error was caused by custom authenticator.
* @return instance of {@link CustomInfo} or null
*/
CustomInfo getCustomInfo();/**
* Returns the {@link UserProfile} object if the profile was deregistered as an effect of the error.
* @return instance of {@link UserProfile} or null
*/
UserProfile getUserProfile();/**
* Returns the {@link OneginiAuthenticator} object of the authenticator was deregistered as an effect of the error.
* @return instance of {@link OneginiAuthenticator} or null
*/
OneginiAuthenticator getAuthenticator();}

For some errors, additional information can be received using this interface. For example, in case of failed authentication with custom authenticator, if the
error was returned by the custom authenticator script on the server side, then the OneginiErrorDetails#getCustomInfo will return the
error details provided by the script (error code and data).

Error codes

Every error has a code. This code uniquely identifies an error. For example the OneginiAuthenticationError class contains the following errors:

from 9000 to 10.000: These codes are reserved for errors that you should show to your end-users. (E.g. they indicate that there was a connection problem
with the Token Server or that the app version that is used by the end-user is outdated)

10.000 and higher: These are errors that usually will not happen or might indicate that there is a misconfiguration in the Token Server.

Example error handling code

It is not required to handle all errors that are returned by the SDK. You may decide based on the requirements of the application you are building which errors
you find interesting and which you don't. The errors which are interesting for you can be easily selected; and for those errors you can implement specific error
handling. Other errors can be combined into more generic error handling, such a showing to the end-user that something went wrong.

The example below shows how you can handle the errors that may occur during user registration:

Error map

We have compiled a matrix of SDK methods and errors. This provides an easy overview of which errors
may occur in every SDK method. Unfortunately it is too big to show it on the current page. Hence you must click on the previous link to view this matrix.