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:
- Determine whether the REST API request succeeded or failed, based on the HTTP status response code returned.
- If the REST API request failed and the response is application/json, serialize the model.
- 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.
- Decide if you want to handle "iServerCode" errors.
A detailed explanation of each step is provided below.
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
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.
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,):
"message": "MicroStrategy Intelligence Server is not configured to support LDAP authentication."
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
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.