Error handling
This topic guide describes how errors should be handled that are generated by the iOS SDK. First we start with a general description on errors from which we slowly dive deeper into the world of error handling for the iOS SDK.
General description
Interaction with the SDK can result in errors. All errors are defined in the ONGErrors
header file. Not all errors that are defined can happen in every
action. The Appledocs for an error parameter will describe which errors can be thrown. We used the error domain to group certain errors together. Hence,
for the authenticate user functionality you can see that only errors from the ONGGenericErrorDomain
will be returned. This means that the following errors
can occur during user authentication:
Apart from these error codes we will also provide you with a comprehensive error description and recovery suggestion. 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.
Error codes
Every error has a code. This code uniquely identifies an error. There are two ranges of error codes:
- from 9000 to (not including) 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
Below follows an example implementation of challenge error handling:
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 iOS SDK error map. 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.
Underlying errors
Error objects returned from the SDK methods can often contain underlying error objects representing errors returned by lower subsystems. These errors, provides you more specific information behind the reason of an error that occurred. It is a good practice to inform the user about all user related errors that occurred, since all of them might contain information that are helpful to the user.