Common Exceptions
Important
Connectors continue to be released outside the IDM release. For the latest documentation, refer to the ICF documentation.
The following sections describe the commonly used exceptions that can be thrown, depending on the operation.
AlreadyExistsException
The AlreadyExistsException is thrown if a create operation attempts to create an object that exists prior to the method execution, or if an update operation attempts to rename an object to that exists prior to the method execution.
ConfigurationException
A ConfigurationException is thrown if a configuration problem is encountered when the connector bundles are loaded. A ConfigurationException can also be thrown during validation operations in the SPI.
ConnectionBrokenException
A ConnectionBrokenException is thrown when a connection to a target resource instance fails during an operation. An instance of the ConnectionBrokenException generally wraps the native exception (or describes the native error) that is returned by the target resource.
ConnectionFailedException
A ConnectionFailedException is thrown when a connector cannot reach the target resource. An instance of the ConnectionFailedException generally wraps the native exception (or describes the native error) that is returned by the target resource.
ConnectorException
This is the base exception for the connector framework. The framework only throws exceptions that extend ConnectorException.
ConnectorIOException
This is the base exception for all Input-Output (I/O-related) exceptions, including instance connection failure, socket error and so forth.
ConnectorSecurityException
This is the base exception for all security-related exceptions.
InvalidAttributeValueException
An InvalidAttributeValueException is thrown when an attempt is made to add to an attribute a value that conflicts with the attribute's schema definition. This might happen, for example, in the following situations:
The connector attempts to add an attribute with no value when the attribute is required to have at least one value
The connector attempts to add more than one value to a single valued-attribute
The connector attempts to add a value that conflicts with the attribute type
The connector attempts to add a value that conflicts with the attribute syntax
InvalidCredentialException
An InvalidCredentialException indicates that user authentication has failed. This exception is thrown by the connector when authentication fails, and when the specific reason for the failure is not known. For example, the connector might throw this exception if a user has entered an incorrect password, or username.
InvalidPasswordException
An InvalidPasswordException is thrown when a password credential is invalid.
OperationTimeoutException
An OperationTimeoutException is thrown when an operation times out. The framework cancels an operation when the corresponding method has been executing for longer than the limit specified in APIConfiguration.
PasswordExpiredException
A PasswordExpiredException indicates that a user password has expired. This exception is thrown by the connector when it can determine that a password has expired. For example, after successfully authenticating a user, the connector might determine that the user's password has expired. The connector throws this exception to notify the application, which can then take the appropriate steps to notify the user.
PermissionDeniedException
A PermissionDeniedException is thrown when the target resource will not allow a connector to perform a particular operation. An instance of the PermissionDeniedException generally describes a native error (or wraps a native exception) that is returned by the target resource.
PreconditionFailedException
A PreconditionFailedException is thrown to indicate that a resource's current version does not match the version provided. This exception is equivalent to the HTTP status: 412 Precondition Failed.
PreconditionRequiredException
A PreconditionRequiredException is thrown to indicate that a resource requires a version, but that no version was supplied in the request. This exception is equivalent to the HTTP status: 428 Precondition Required.
RetryableException
A RetryableException indicates that the failure might be temporary, and that retrying the same request might succeed in the future.
UnknownUidException
An UnknownUidException is thrown when a UID that is specified as input to a connector operation identifies no object on the target resource. When you implement the AuthenticateOp, your connector can throw this exception if it is unable to locate the account necessary to perform authentication.
NullPointerException (c# NullReferenceException)
Generic native exception
UnsupportedOperationException (c# NotSupportedException)
Generic native exception
IllegalStateException (c# InvalidOperationException)
Generic native exception
IllegalArgumentException (c# ArgumentException)
Generic native exception
Mapping ICF Exceptions to ForgeRock® Common REST Exceptions
The following table maps the errors that are thrown by the OpenICF framework to the errors that are returned by the Common REST implementation.
| ICF Exception | Common REST Exception | HTTP Error Code |
|---|---|---|
| AlreadyExistsException | ConflictException | |
| ConfigurationException | InternalServerErrorException | |
| ConnectionBrokenException | InternalServerErrorException | |
| ConnectionFailedException | ConnectionFailedException | |
| ConnectorException | InternalServerErrorException | |
| ConnectorIOException | InternalServerErrorException | |
| ConnectorSecurityException | ForbiddenException | |
| InvalidAttributeValueException | BadRequestException | |
| InvalidCredentialException | ForbiddenException | |
| InvalidPasswordException | ForbiddenException | |
| OperationTimeoutException | ||
| PasswordExpiredException | ForbiddenException | |
| PermissionDeniedException | ForbiddenException | |
| PreconditionFailedException | PreconditionFailedException | |
| PreconditionRequiredException | PreconditionRequiredException | |
| RetryableException | RetryableException (ServiceUnavailableException) | |
| UnknownUidException | NotFoundException | |
| UnsupportedOperationException | NotSupportedException | |
| IllegalArgumentException | InternalServerErrorException | |
| NullPointerException | InternalServerErrorException |