Exceptions and Error Codes

General Exceptions and Error Codes

The following exceptions are generically classified as system level exceptions. These are considered general exceptions that occur infrequently and often imply a systemic issue. As a result, these error codes are grouped into the following two exception types: ManagementException and SessionException.

ManagementException

Thrown in response to unexpected and unrecoverable errors within the client or server. ManagementExceptions are typically non-recoverable and are usually related to systemic issues such as mis-configuration, connectivity issues, an inability to lookup device identifiers, or resource unavailability.

SessionException

Thrown in cases where an error condition is encountered caused by session anomalies (such as a session is not open or a session is no longer valid or session permission is denied. The following table describes the maximum session error code.

Maximum Session Error Codes

Error Code

Description

AIMS_CONNECTION_TIMEOUT

The session has expired.

AIMS_MAX_SESSION_REACHED

This is the value returned whenever the maximum number of sessions has been reached on the server for the corresponding manager.

AIMS_OPERATOR_PERMISSION_DENIED

The operator has insufficient permissions for the API call.

AIMS_SESSION_NOT_OPENED

The API call requires a valid session open.

AIMS_UNEXPECTED_CLIENT_ERROR

The session was interupted or closed prematurely by the client.

Other Exceptions

This section lists the exceptions occuring when there are issues that are related to operations, parameters, actions, data-specific, or other types of activity-related causes.

Thrown when an error has occurred in the fetching of a manager instance.

Thrown when invalid or disallowed enrollment data or parameters, action types, or action sequences are detected.

Thrown when a specific implementation of the ManagerFactory does not receive a specific implementation of the Manager interface.

Thrown when an attempt is made to set a lifecycle state that is invalid for the referenced object(s).

This is the base class for all exceptions returned by the CCM API.

Exception thrown by the web service layer. This exception is thrown only when the most severe, unexpected, SOAP-level failures occur. ActivID CMS supports uniform error codes that are returned when there are communication or connectivity-related issues. See the following table.

Communication and Connectivity Error Codes

Error Code

Description

AIMS_CONNECTION_TIMEOUT

A timeout occurred when connecting to the server.

AIMS_HTTP_SESSION_ERROR

An error occurred when establishing a session with the server (for example, server down or resolving DNS).

AIMS_UNSUPPORTED_METHOD

The invoked method is not supported by the server.

AIMS_SSL_SESSION_ERROR

An SSL/TLS session-related error occurred.

AIMS_UNEXPECTED_CLIENT_ERROR

A client-based error occurred.

Thrown when there are errors that occur during the instantiation of the class that is returned by the LookupService. Some possible reasons for instantiation errors include the following:

  • InstantiationException

  • IllegalAccessException

  • The class that was returned did not represent the class that implemented the ManagerInstance

Thrown when the class that is defining a ManagerInstance is not found. A ManagerInstance might not be found for the following reasons:

  • No properties files were found that correspond to factoryDefinition

  • None of the properties files that met the factoryDefinition had the provider as a key

Thrown when invalid data is passed to a manager API call.

Thrown when invalid enrollment data is passed.

Thrown when an attempt is made to retrieve or operate on an action that does not exist.

Thrown when the specified security module is not bound to any user.

Thrown when the specified configuration or profile is not found.

Thrown if the specified credential is not found.

Thrown if the specified enrollment data does not exist.

Thrown when an attempt is made to retrieve an attribute on a profile that does not exist.

Thrown if the specified search handle is invalid.

Thrown when a security module identifier does not correspond to a valid security module.

Thrown when the specified transaction is not found.

Thrown when a specified user could not be found.

Thrown when an attempt is made to retrieve or operate on a wallet that does not exist.

Thrown when the discovered security module is not in a valid state for synchronization.

This exception is thrown by the isSyncRequired method under Synchronization Manager when ActivID CMS determines that the security module is not in a valid state for synchronization.

The NotSyncableStateException exposes both the reason and the value attributes for the corresponding setter and getter methods. ActivID CMS supports the reasons and corresponding values listed in the following table.

Reasons and Values for NotSyncableStateException

Thrown when a limit of a search dataset is reached by either paging forward to the end or paging back to the beginning of the dataset.

Thrown when an attempt is made to bind a security module already bound to another wallet.

Thrown if a security module is not bound when it was expected to be.

Thrown if an attempt to cancel a synchronization is rejected.

Thrown when an unexpected failure has occurred in the implementation layer.

Thrown if a synchronization is attempted to be cancelled and the cancel is rejected.

Thrown when premature retrieval is attempted for an object based on a transaction. Thrown when an intermediate state transaction fails to provide some end result data.

Thrown if the user that was to be added already exists.

Backward Compatibility Implementation Considerations

This section provides descriptions of how the Java and C++ implementations address backward compatibility for the LocalizedRemoteException class.

To avoid any backward compatibility issues with existing applications, the Java implementation of the LocalizedRemoteException class is derived from the java.rmi.RemoteException base class, which is also the class defined in the API interface classes.

If any application needs to explicitly access the new error codes that are returned by ActivID CMS, that application must typecast (changing an entity of one datatype into another datatype) the received exception into a LocalizedRemoteException to access the error code value.

To avoid any backward compatibility with existing applications, the C++ implementation of the LocalizedRemoteException class is derived from the SessionException.