Handle REST API Exceptions

When developers use MicroStrategy REST APIs to build dynamic applications, they need to add code to handle errors that may be encountered. The instructions below are designed to provide guidance on designing exception workflows when using MicroStrategy REST APIs.

To deal with exceptions, the recommended practice is to follow the sequence outlined below:

1. Determine whether the REST API request succeeded or failed, based on the HTTP status response code returned.
2. If the REST API request failed and the response is application/json, serialize the model.
3. Look at the error code that was returned to determine if it provides insight into what caused the exception and use that insight to create meaningful text for the error message.
4. Decide if you want to handle "iServerCode" errors.

A detailed explanation of each step is provided below.

1. Determine whether the REST API request succeeded or failed, based on the HTTP status response code returned.

   The HTTP status response code returned by the REST API call indicates whether the request succeeded or failed.

   HTTP status response code	Description
   2xx (Successful)	The request was successfully received, understood, and accepted
   3xx (Redirection)	Further action needs to be taken in order to complete the request
   4xx (Client error)	The request contains bad syntax or cannot be fulfilled (bad request, authorization issue, etc.)
   5xx (Server error)	The server failed to fulfill an apparently valid request

2. If the REST API request failed and the response is application/json, serialize the model.

   JSON is a format that encodes objects in a string. To return the response as JSON, you must serialize the model so that the data can be transmitted as a string.

3. Look at the error code that was returned to determine if it provides insight into what caused the exception and use that insight to create meaningful text for the error message.

   When you execute a REST API call and encounter an exception, you receive an error message that looks like the sample code shown below (if it is returned in a JSON format,):

   {

     "code": "ERR001",

     "message": "MicroStrategy Intelligence Server is not configured to support LDAP authentication."

     "iServerCode": -2147205409,

   }

   The value of code in the error message is a MicroStrategy error code. The table below provides a general description of each error code. Use the error code to create meaningful text for the error message that will help users when they encounter errors.

   Error code	Description
   ERR001	General application issue
   ERR002	IServer error
   ERR003	Authentication error
   ERR004	Resource not found
   ERR005	Missing required information
   ERR006	Invalid input
   ERR007	Missing required field
   ERR008	Inbox message not ready
   ERR009	Session invalid or timeout
   ERR010	Not supported
   ERR013	IServer unreachable
   ERR014	Insufficient privileges
   ERR015	Object already exists
   ERR016	Service not available
   ERR017	Insufficient permission
   ERR020	Dashboard prompt not supported
   ERR021	Invalid configuration property
   ERR022	Service TLS validation issue
   ERR023	Secret Key configuration issue
   ERR024	Trust store configuration issue

4. Decide if you want to handle "iServerCode" errors

   The MicroStrategy error message that is returned also contains an integer value for iServerCode. This integer value maps to a constant in the WebAPIErrorCodes class. There are many error codes in this class. You should look at the iServerCode error and decide if you think it provides meaningful context. If so, you may want to handle it in your code.