Error handling
Interaction with the cSDK 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 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.
Error codes
Every error includes a code. There are two ranges of error codes:
- From 9000 to 10.000: These codes are reserved for errors that you should show to your users. For example, they indicate that there was a connection problem with the IDAAS-core or that the app version that is used by the 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 IDAAS-core.
// Swift errors are not converted to Swift yet.
/// Due to a problem with the device internet connection it was not possible to initiate the requested action.
ONGGenericErrorNetworkConnectivityFailure = 9000,
/// Check the SDK configuration for the correct server URL.
ONGGenericErrorServerNotReachable = 9001,
/// The device registration was removed. 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 Mobile Identity module 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 Mobile Identity module 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 IDAAS-core configuration is invalid.
ONGGenericErrorConfigurationInvalid = 10001,
/// The request to the IDAAS-core was invalid. Please verify that the IDAAS-core configuration is correct and that no reverse proxy is interfering with the connection.
ONGGenericErrorRequestInvalid = 10015,
/// The device could not be registered with the IDAAS-core, verify that the SDK configuration, IDAAS-core 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 IDAAS-core.
ONGGenericErrorAppIntegrityFailure = 10024,
Apart from these error codes, we also provide a comprehensive error description and recovery suggestion. The error description is in English and intended for developers to understand what happened. They are not intended for users.
Example error handling code
The following example shows an implementation of challenge error handling.
It is not required to handle all errors that are returned by the iOS 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 that are interesting for you can be easily selected. For those errors, you can implement specific error handling. Other errors can be combined into more generic error handling, such a showing to the user that something went wrong.
The example below shows how you can handle the errors that may occur during user registration:
Example: handling user registration errors
func userClient(_ userClient: UserClient,
didFailToRegisterWith identityProvider: IdentityProvider,
error: Error) {
// 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 IDAAS-core, verify that the SDK configuration, IDAAS-core configuration and security features are correctly configured
case ONGRegistrationError.deviceRegistrationFailure.rawValue:
// A possible security issue was detected during User Registration.
case ONGRegistrationError.invalidState.rawValue:
// display an error to the user, hide registration UI, etc
// Generic errors
// In case the user has cancelled the PIN challenge, the cancellation error will be reported. This error can be ignored.
case ONGGenericError.actionCancelled.rawValue:
// Undefined error occurred
case ONGGenericError.unknown.rawValue:
// Typical network errors
case ONGGenericError.networkConnectivityFailure.rawValue:
case ONGGenericError.serverNotReachable.rawValue:
// 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 ONGGenericError.requestInvalid.rawValue:
// The user trying to perform registration, but previous registration is not finished yet.
case ONGGenericError.actionAlreadyInProgress.rawValue:
// 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 ONGGenericError.outdatedApplication.rawValue:
case ONGGenericError.outdatedOS.rawValue:
default:
// display error.
}
show(error)
completion()
}
- (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 IDAAS-core, verify that the SDK configuration, IDAAS-core 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];
}
Mobile SDK errors
The following is a description of all errors that can occur in the iOS SDK:
Error | Code |
---|---|
NETWORK_CONNECTIVITY_PROBLEM | 9000 |
SERVER_NOT_REACHABLE | 9001 |
DEVICE_DEREGISTERED | 9002 |
USER_DEREGISTERED | 9003 |
OUTDATED_APP | 9004 |
OUTDATED_OS | 9005 |
ACTION_CANCELED | 9006 |
ACTION_ALREADY_IN_PROGRESS | 9007 |
DEVICE_REGISTRATION_ERROR | 9008 |
USER_NOT_AUTHENTICATED | 9010 |
PIN_BLACKLISTED | 9011 |
PIN_IS_A_SEQUENCE | 9012 |
PIN_USES_SIMILAR_DIGITS | 9013 |
WRONG_PIN_LENGTH | 9014 |
INVALID_AUTHENTICATOR | 9015 |
DEVICE_ALREADY_ENROLLED | 9016 |
ENROLLMENT_NOT_AVAILABLE | 9017 |
USER_ALREADY_ENROLLED | 9018 |
USER_DISENROLLED | 9020 |
MOBILE_AUTHENTICATION_NOT_ENROLLED | 9021 |
AUTHENTICATOR_DEREGISTERED | 9022 |
MOBILE_AUTHENTICATION_DISENROLLED | 9023 |
DATA_STORAGE_NOT_AVAILABLE | 9024 |
CUSTOM_AUTHENTICATOR_FAILURE | 9027 |
ALREADY_HANDLED | 9029 |
INVALID_DATETIME | 9031 |
GENERAL_ERROR | 10000 |
CONFIGURATION_ERROR | 10001 |
INVALID_STATE | 10002 |
LOCAL_DEREGISTRATION | 10003 |
AUTHENTICATOR_ALREADY_REGISTERED | 10004 |
FIDO_AUTHENTICATION_DISABLED (DEPRECATED) | 10005 |
AUTHENTICATOR_NOT_SUPPORTED | 10006 |
AUTHENTICATOR_NOT_REGISTERED | 10007 |
AUTHENTICATOR_PIN_DEREGISTRATION_NOT_POSSIBLE | 10008 |
LOCAL_LOGOUT | 10009 |
DEVICE_NOT_AUTHENTICATED | 10012 |
MOBILE_AUTHENTICATION_REQUEST_NOT_FOUND | 10013 |
INVALID_REQUEST | 10015 |
FIDO_SERVER_NOT_REACHABLE (DEPRECATED) | 10016 |
CUSTOM_AUTHENTICATION_DISABLED | 10017 |
NOT_HANDLEABLE | 10018 |
INVALID_IDENTITY_PROVIDER | 10020 |
CUSTOM_REGISTRATION_EXPIRED | 10021 |
CUSTOM_REGISTRATION_FAILURE | 10022 |
SINGLE_SIGN_ON_DISABLED | 10023 |
APP_INTEGRITY_FAILURE | 10024 |