Error handling

This topic guide describes how errors should be handled that are generated by the Onegini 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 Onegini 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:

/// Due to a problem with the device internet connection it was not possible to initiate the requested action.
ONGGenericErrorNetworkConnectivityFailure = 9000,
/// Check the Onegini SDK configuration for the correct server URL.
ONGGenericErrorServerNotReachable = 9001,
/// The device registration was removed from the Token Server. All locally stored data is removed from the device and the user needs to register again.
ONGGenericErrorDeviceDeregistered = 9002,
/// The user account is deregistered from the device. The user supplied the wrong PIN for too many times. All local data associated with the user profile has been removed.
ONGGenericErrorUserDeregistered = 9003,
/// The Token Server denotes that the current app is no longer valid and can no longer be used. The end-user must update the application. Updating the SDK configuration might also solve the problem.
ONGGenericErrorOutdatedApplication = 9004,
/// The Token Server does not allow this application to run on the current OS version. Instruct the user to update the OS.
ONGGenericErrorOutdatedOS = 9005,
/// Requested action was cancelled.
ONGGenericErrorActionCancelled = 9006,
/// Another action already in progress and can not be performed concurrently.
ONGGenericErrorActionAlreadyInProgress = 9007,
/// An unknown error occurred
ONGGenericErrorUnknown = 10000,
/// The Token Server configuration is invalid.
ONGGenericErrorConfigurationInvalid = 10001,
/// The request to the Token Server was invalid. Please verify that the Token Server configuration is correct and that no reverse proxy is interfering with the connection.
ONGGenericErrorRequestInvalid = 10015,
/// The device could not be registered with the Token Server, verify that the SDK configuration, Token Server configuration and security features are correctly configured.
ONGGenericErrorDeviceRegistrationFailure = 9008,
/// The data storage could not be accessed.
ONGGenericErrorDataStorageNotAvailable = 9024,
/// The data storage is corrupted and cannot be recovered or cleared.
ONGGenericErrorUnrecoverableDataState = 9025
/// Application integrity check failed. Please verify application signature on the Token Server.
ONGGenericErrorAppIntegrityFailure = 10024,

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:

- (void)userClient:(ONGUserClient *)userClient didFailToRegisterWithError:(NSError *)error identityProvider:(ONGIdentityProvider *)identityProvider
{
    // Errors are going to be within ONGGenericErrorDomain or ONGRegistrationErrorDomain domains.
    switch (error.code) {
        // Both errors from ONGRegistrationErrorDomain mean that registration can not be completed.
        // Most likely you will encounter them only during development with invalid configuration.

        // The device could not be registered with the Token Server, verify that the SDK configuration, Token Server configuration and security features are correctly configured
        case ONGRegistrationErrorDeviceRegistrationFailure:
            // A possible security issue was detected during User Registration.
        case ONGRegistrationErrorInvalidState:
            // display an error to the user, hide registration UI, etc
            break;

            // Generic errors
            // In case the user has cancelled the PIN challenge, the cancellation error will be reported. This error can be ignored.
        case ONGGenericErrorActionCancelled:
            break;

            // Undefined error occurred
        case ONGGenericErrorUnknown:

            // Typical network errors
        case ONGGenericErrorNetworkConnectivityFailure:
        case ONGGenericErrorServerNotReachable:

            // This error should not happen in the Production because it means that the configuration is invalid and / or server has proxy.
            // Developer will most likely face with such errors during development itself.
        case ONGGenericErrorRequestInvalid:

            // The user trying to perform registration, but previous registration is not finished yet.
        case ONGGenericErrorActionAlreadyInProgress:

            // You typical won't face the ONGGenericErrorOutdatedApplication and ONGGenericErrorOutdatedOS during PIN change.
            // However it is potentially possible, so we need to handle them as well.
        case ONGGenericErrorOutdatedApplication:
        case ONGGenericErrorOutdatedOS:

        default:
            // display error.
            break;
    }

    [self showError:error];

    self.completion();
}

- (void)showError:(NSError *)error
{
    [self.navigationController popToRootViewControllerAnimated:YES];
    UIAlertController *alert = [UIAlertController alertControllerWithTitle:@"Registration Error"
                                                                   message:error.localizedDescription
                                                            preferredStyle:UIAlertControllerStyleAlert];
    UIAlertAction *okButton = [UIAlertAction actionWithTitle:@"Ok"
                                                       style:UIAlertActionStyleDefault
                                                     handler:nil];
    [alert addAction:okButton];
    [self.navigationController presentViewController:alert animated:YES completion:nil];
}

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.

Underlying errors

Error objects returned from the Onegini 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.