Error Handling

The Designer API uses HTTP status codes and a standard JSON response format to communicate the results of an API operation to clients.

If an error occurs while processing a request, the API will return an HTTP status code and a JSON error object with a message field and a details field. The message field contains a general description of the error, the details field contains more specific information about the error or partial-errors.

To handle errors effectively in your API integration, you should always check the HTTP status code of the API response and handle any errors appropriately. In most cases you should at a minimum display the provided status.message string to the user of your application, this will always be user friendly and contain details about the error which can be further investigated using the Designer GUI.

It is also a good idea to log any errors that occur during API operations for further analysis and debugging. If you need to contact disguise support with an API related issue it is useful to include both a Project Diagnostic as well as examples and logs of your API usage.

HTTP Status Codes

In order to handle errors effectively, it is important to first understand the different types of HTTP status codes that may be returned by the API. The Designer API uses a simple scheme of status codes to easily determine the source of any error.

Code	Summary	Description
200	Success	The user request was successfully received, accepted, and processed.
400	Client Error	The user request was not fulfilled due to a problem with the request syntax or other client issues.
404	Not Found	The requested endpoint cannot be located. The API either cannot map the user request URI to an endpoint, or the endpoint is no longer available.
500	Server Error	The user request appeared valid, but was not fulfilled due to an issue with the server.

Standard Response

The API returns a standard response to all requests which includes the status of the specific request and possibly a result field. This allows for easy error handling within client applications and more detailed error information than the HTTP Status Code.

The following JSON object is returned for all requests:

{
  "status": { // common status structure
      "code": 0, // non-zero if an error occurs
      "message": "string", // user friendly error description
      "details": [
          // array of details about the error including user friendly descriptions
          {
            "message": "string"
          }
      ]
  },
  "result": {} // result of the API operation
}

Both the status and details fields include user-friendly message strings that can be displayed directly to the user of an API-based application.

If a request includes multiple actions, such as triggering multiple transports, each individual error related to an action will be included in the details field. The order and size of the details field is not guaranteed.

Sample Code

This example demonstrates a transport command request which partially fails. Because this is a partial failure, error code 200 is returned.

We use the response status.code field to identify an error has occured. We then use the status.message field to inspect the failure and report detailed information by iterating the details field. In a real-world application we would display these messages directly to the user alongside the existing logging.

fetch('/api/session/transport/gototrack', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ transports: [{ 
        transport: { name: 'does not exist' }, // missing transport specified
        track: { name: 'track 1' }, 
        playMode: 'playsection' 
      }]
    })
  })
  .then(response => {
    console.log('Response HTTP Code: ', response.status) // 200 because the request partially succeeded
    return response.json()
  })
  .then(data => {
    if (data.status.code != 0) {
      console.log('Failure Status Code: ', data.status.code) // non-zero to indicate something went wrong
      console.log('Failure Status Message: ', data.status.message) // message indicates one or more transport commands failed
      data.status.details.forEach(detail => console.log('Failure Status Detail: ', detail.message)) // we will have a details entry for each error reported
    } else {
      console.log('Successful Results: ', data.results);
    }
  });