Version 2021

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.