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,
- ACTION_ALREADY_IN_PROGRESS,
- AUTHENTICATOR_NOT_REGISTERED,
- INVALID_AUTHENTICATOR,
- CUSTOM_AUTHENTICATOR_FAILURE,
- CUSTOM_AUTHENTICATION_DISABLED,
- AUTHENTICATOR_DEREGISTERED,
- DATA_STORAGE_NOT_AVAILABLE.
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.
For a full list of all errors including a comprehensive description go to the Errors reference guide.
OneginiError
also contains an instance of OneginiErrorDetails
that can be accesed by calling getErrorDetails()
.
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:
There are two ranges of error codes:
- 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.