Error response objects

If a request is unsuccessful, an error response object is returned. The object returned depends on the request type, number of items in the request, and the problem that occurred.

errorResponse object

An errorResponse object provides basic information about an unsuccessful request.

Parameter	Tyoe	Description
code	string	Short description of error type
message	string	Long description or message about the error. This may be a message you want to display to a user in your application.
statusCode	integer	HTTP status code. See Error and response codes.

Example

This example shows the error response for a Forbidden error (http status code 403). In this case, the user does not have an issue management license, so the request is unsuccessful.

{
    "message": "Items of type \"issues\" are not allowed in this request due to security settings.",
    "statusCode": 403,
    "code": "Forbidden"
}

errorElementPath object

An errorElementPath object is returned if a problem occurs when sending data to the server, typically for a PUT or POST request. It includes the same information as the errorResponse object plus a path to where the problem occurred so you can trace back in your code to find and fix it.

Parameter	Tyoe	Description
code	string	Short description of error type
message	string	Long description or message about the error
statusCode	integer	Error type identifier. See Error and response codes.
errorElementPath	string	Path to the object that caused an error if there was a problem sending data to the server

Example

This example shows the error response for a Bad Request error (http status code 403).

Request

The error occurs when submitting the following POST /{projectID}/issues request.

{
    "issues": [
        {
            "events": {
            	"eventsData": [
            		{
            			"name": "Comment"
            		}]
            },
            "fields": [
                {
                    "id": 2,
                    "label": "Summary",
                    "string": "A basic issue that  will start with a comment on it.",
                    "type": "string"
                },
                {
                    "id": 4,
                    "label": "Type",
                    "menuItem": {
                        "id": 3,
                        "label": "Incorrect Functionality"
                    },
                    "type": "menuItem"
                },
                {
                    "id": 3,
                    "label": "Product",
                    "menuItem": {
                        "id": 5,
                        "label": "Activity Professional Suite (APS)"
                    },
                    "type": "menuItem"
                }
            ]
        },
        {
            "events": {
            	"eventsData": [
            		{
            			"name": "Fix"
            		}]
            },
            "fields": [
                {
                    "id": 2,
                    "label": "Summary",
                    "string": "An invalid issue that will fail to be created because the 'Fix' event is invalid for this new issue's starting state.",
                    "type": "string"
                },
                {
                    "id": 4,
                    "label": "Type",
                    "menuItem": {
                        "id": 3,
                        "label": "Incorrect Functionality"
                    },
                    "type": "menuItem"
                },
                {
                    "id": 3,
                    "label": "Product",
                    "menuItem": {
                        "id": 5,
                        "label": "Activity Professional Suite (APS)"
                    },
                    "type": "menuItem"
                }
            ]
        }
    ]
}

Error

The error occurs because the Fix workflow event is in the request, but it is not a valid event to enter when an issue is in the Open state.

The errors array contains the error information. In addition to the message, status code, and code parameters, the errorElementPath parameter shows the path to where the error occurred in the request: /issues/1/events/eventsData/0. The path indicates that the error occurred because of data in the in first eventData object, which is indicated by 0 because it is a zero-based array, in the second events object (indicated by 1) in the array.

{
    "errors": [
        {
            "message": "The Fix workflow event is not valid for the Open state.",
            "statusCode": 400,
            "code": "Bad Request",
            "errorElementPath": "/issues/1/events/eventsData/0"
        }
    ]
}

errorResponseArray object

An errorResponseArray object is returned if multiple errors occur in a request. For example, this object may be returned if a 206 error (partial success) occurs on a POST request that contains multiple issues.

Parameter	Tyoe	Description
code	string	Short description of error type
message	string	Long description or message about the error
statusCode	integer	Error type identifier. See Error and response codes.
errorElementPath	string	Path to the object that cause an error if there was a problem sending data to the server

Example

This example shows a Partial Success response (http status code 206). For example, this error may occur when a POST request with multiple issues has a problem with one issue, but changes to another issue are successful.

The errorResponseArray object contains an errors array with one error and an issues array with one stub to indicate the issue that was successfully updated.

{
    "errors": [
        {
            "message": "The Fix workflow event is not valid for the Open state.",
            "statusCode": 400,
            "code": "Bad Request",
            "errorElementPath": "/issues/1/events/eventsData/0"
        }
    ],
    "issues": [
        {
            "httpURL": "http://127.0.0.1/ttweb/index.html#Default/289/issues/56/detail",
            "id": 56,
            "number": 56,
            "self": "https://localhost:8443/helix-alm/api/v0/Traditional_Template/issues/56",
            "tag": "IS-56",
            "ttstudioURL": "ttstudio://pvincent:99//Traditional_Template/dfct?recordID=56"
        }
    ]
}