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.

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().

/**
 * An interface to return additional error details when needed.
 */
public interface OneginiErrorDetails {

  /**
   * 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:

public class OneginiAuthenticationError implements OneginiError {
  public static final int GENERAL_ERROR = 10000;
  public static final int NETWORK_CONNECTIVITY_PROBLEM = 9000;
  public static final int SERVER_NOT_REACHABLE = 9001;
  public static final int DEVICE_DEREGISTERED = 9002;
  public static final int CONFIGURATION_ERROR = 10001;
  public static final int USER_DEREGISTERED = 9003;
  public static final int OUTDATED_APP = 9004;
  public static final int OUTDATED_OS = 9005;
  public static final int ACTION_CANCELED = 9006;
  public static final int AUTHENTICATOR_NOT_REGISTERED = 10_007;
  public static final int INVALID_AUTHENTICATOR = 9015;
  public static final int CUSTOM_AUTHENTICATOR_FAILURE = 9027;
  public static final int CUSTOM_AUTHENTICATION_DISABLED = 10_017;
  public static final int AUTHENTICATOR_DEREGISTERED = 9022;
  // ...

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:

private void registerUser() {
  final OneginiClient oneginiClient = OneginiSDK.getOneginiClient(this);
  oneginiClient.getUserClient().registerUser(null, Constants.DEFAULT_SCOPES, new OneginiRegistrationHandler() {

    @Override
    public void onSuccess(final UserProfile userProfile) {
      PinActivity.setRemainingFailedAttempts(0);
      registeredProfile = userProfile;
      userProfileDebugText.setText(userProfile.getProfileId());
      askForProfileName();
    }

    @Override
    public void onError(final OneginiRegistrationError oneginiRegistrationError) {
      handleRegistrationErrors(oneginiRegistrationError);
    }
  });
}

private void handleRegistrationErrors(final OneginiRegistrationError oneginiRegistrationError) {
  @OneginiRegistrationError.RegistrationErrorType final int errorType = oneginiRegistrationError.getErrorType();
  switch (errorType) {
    case OneginiRegistrationError.DEVICE_DEREGISTERED:
      showToast("The device was deregistered, please try registering again");
      new DeregistrationUtil(this).onDeviceDeregistered();
      break;
    case OneginiRegistrationError.ACTION_CANCELED:
      showToast("Registration was cancelled");
      break;
    case OneginiRegistrationError.NETWORK_CONNECTIVITY_PROBLEM:
    case OneginiRegistrationError.SERVER_NOT_REACHABLE:
      showToast("No internet connection.");
      break;
    case OneginiRegistrationError.OUTDATED_APP:
      showToast("Please update this application in order to use it.");
      break;
    case OneginiRegistrationError.OUTDATED_OS:
      showToast("Please update your Android version to use this application.");
      break;
    case OneginiRegistrationError.GENERAL_ERROR:
    default:
      // General error handling for other, less relevant errors
      handleGeneralError(oneginiRegistrationError);
      break;
  }
}

private void handleGeneralError(final OneginiRegistrationError error) {
  final StringBuilder stringBuilder = new StringBuilder("Error: ");
  stringBuilder.append(error.getMessage());
  stringBuilder.append(" Check logcat for more details.");

  error.printStackTrace();

  showToast(stringBuilder.toString());
}

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.