Handling errors and exceptions

When exceptions occur, the BlackBerry® Administration API can throw standard SOAP exceptions. You can use try-catch blocks, or the equivalent in your chosen language, with all API methods to handle the SOAP exceptions. When errors occur in the BlackBerry Administration API, the errors are described in a return status object.

Single-object APIs use return objects that contain a return status object of the type <MethodName>ReturnStatus, where MethodName is the name of the API method your application has called. The return status object describes the error.

Multi-object APIs use return objects that contain an array of return status objects and a global return status object. The array of return status objects describes the errors that prevent individual objects from being processed. The global return status object describes the errors that prevent all objects from being processed. When using multi-object APIs, your application should examine both the array of return status objects and the global return status object.

For example, if your application attempts to move five user accounts to a different BlackBerry® Enterprise Server but the BlackBerry Enterprise Server is unavailable, the error is described in the global return status object and none of the user accounts are moved. If the BlackBerry Enterprise Server is available but two of the five user accounts do not exist, the BlackBerry Administration API moves the three existing user accounts and throws an exception that contains two nested return objects in the array that describe why the two user accounts were not moved.

Return status attribute

Metadata description

code

This attribute is the error code that is associated with the error that occurred.

actor

This attribute is the origin of the error. The origin is either the client or the server. Client errors occur when the request contains invalid input, such as incorrect authentication credentials or other invalid parameters. Server errors occur when the request is valid and well-formed, but a BlackBerry Enterprise Server component is unavailable.

message

This attribute describes the error that occurred.

Next topic: Glossary
Previous topic: Processing responses

Was this information helpful? Send us your comments.