Helix ALM LogoToday we'll be continuing our series of posts focusing on various features from Perforce's Helix ALM REST API. Today's feature is about the API's error and response codes. If you are unfamiliar with Helix ALM, it is a modular suite of ALM tools that you can use to trace requirements, tests, and issues. ALM stands for Application Lifecycle Management, REST for Representational State Transfer, and API for Application Programming Interface.

The Helix ALM REST API has several endpoints that developers can use for interfacing with their organization's Helix ALM instance. The wide variety of endpoints provide many possibilities for developers to create tools or scripts to aid in their organization's workflow, with few limitations.

The REST API is available at:

https://{API URL}/helix-alm/api/v0/

and the Swagger UI interactive documentation tool is available at:

https://{API URL}:{port}

where {API URL} is the address of the REST API server. The address can be configured in the JSON configuration file of the REST API, typically located at:

../Perforce/Helix ALM/helix-alm-rest-api/config/config.json

on the machine that is running the Helix ALM instance.

Error and Response Codes

The Helix ALM REST API has three kinds of response codes, two of which are error codes. Responses may include a JSON object in the body providing additional information. The first kind of response codes has to do with the 200 range of HTTP responses, the second covers client error codes of the 400 range, and the last are server error codes of the 500 range.

Success Codes

200 - Success

The 200 status code indicates that the request was successful. The response returned is unique to the specific request and may contain data or other relevant information. Typically, for a GET or PUT endpoint response, the data is a JSON object with a single item or a list of items. In the case of the search POST endpoint, it is a list of items that match the search query.

For example, the GET endpoint for querying a list of projects returns a JSON object that looks like:

{
  "projects": [
    {
      "id": 1,
      "name": "{project name}",
      "uuid": "{UUID}"
     },
     {
       "id": 2,
       "name": "{project name}",
       "uuid": "{UUID}"
     },
     etc…
  ],
  "projectsLoading": 0
}

PUT requests generally return the status code 200 when updating a list of objects; otherwise, the PUT request returns status code 204 when updating a specific item. The JSON object returned upon updating a list of items is the same list of the items but a reduced object with only a few name/value pairs in each item. An example of this looks like:

{
  "{item types}": [
    {
      "id": XX,
      "number": YYY,
      "tag": "ZZ-ZZZ",
      "self": "https://{organization}:{port}/helix-alm/api/v0/{project id}/{item type}/{id}",
      "ttstudioURL": "ttstudio://{organization}:{port}//{project id}/dfct?recordID={id}",
      "httpURL": "http://{organization}/ttweb/index.html#Default/{project id}/{item type}/{id}/"
    },
    etc…
  ]
}

201 - Success (Created Item)

When a request to create a new item is successful, the API returns a 201 status code. Similar to the 200 code, the response is specific to the request and may include additional details about the newly created item.

An example of this looks like:

{
  "{item types}": [
    {
      "id": XX,
      "number": YYY,
      "tag": "ZZ-ZZZ",
      "self": "https://{organization}:{port}/helix-alm/api/v0/{project id}/{item type}/{id}",
      "ttstudioURL": "ttstudio://{organization}:{port}//{project id}/dfct?recordID={id}",
      "httpURL": "http://{organization}/ttweb/index.html#Default/{project id}/{item type}/{id}/"
    },
    etc…
  ]
}

204 - Success (Updated Item)

If an item is successfully updated through an API request, a 204 status code is returned. In this case, no additional information is provided in the response.

206 - Partial Success

A 206 status code signifies that the request was partially successful, this error may occur when a PUT or POST request with multiple items has a problem with one item, but changes to or creation of other items are successful. The response contains details about which parts of the request succeeded and which failed.

The response data is an errorResponseArray object, comprised of two parts: the error array and the items array of the updated or created items.

An example where the Steps field is missing a formattedString property looks like:

{
  "errors":[
    {
      "message": "The Steps field must have a formattedString property.",
      "statusCode": 400,
      "code": "Bad Request",
      "errorElementPath": "/{item type}/{index in items array}/fields/{index in fields array}"
    }
  ],
  "{item types}": [
    …
  ]
}

Note: the items array is excluded for brevity and resembles the response body from code 201.

Client Error Codes

When a request is unsuccessful, the server will return one of these error codes. The object in the body depends on the nature of the error. Typically, the object consists of an HTTP status code, a description of the code, along with the error message itself. Some error codes may include the path to the element that caused the error.

400 - Bad Request

When a request is missing required parameters or contains invalid information, the API returns a 400 status code. This indicates that the client needs to modify the request before sending it again.
An example of the error response object returned looks like:

{
  "message": "Validation errors. Invalid parameter (issues): Value failed JSON Schema validation. Expected type string but found type integer",
  "statusCode": 400,
  "code": "Bad Request",
  "errorElementPath": "/issues/0/fields/1/label"
}

The "errorElementPath" value indicates the location of where the offending data was incorrect in the request object.
In our example the error path is "/issues/0/fields/1/label". "issues" is the item type; 0 is the index of the issue in the zero-based array object; "fields" is the object where the error occurred, in the second field object (denoted by 1), at the label value.

401 - Unauthorized

A 401 status code means that access is denied due to incorrect or unrecognized credentials, such as an invalid username/password combination or an expired access token.

{
  "message": "Access denied",
  "statusCode": 401,
  "code": "Unauthorized"
}

403 - Forbidden

If a user doesn't have the necessary permissions to perform the requested action, a 403 status code is returned. This could be due to various reasons, such as not having a valid license, not being part of the requested project, or lacking the required security commands.

{
  "message": "You cannot log in to this project.",
  "statusCode": 403,
  "code": "Forbidden"
}

404 - Not Found

When the requested record or resource cannot be found, the API returns a 404 status code.

{
  "message": "No project found with name \"Unknown Project\"",
  "statusCode": 404,
  "code": "Not Found"
}

409 - Conflict

A 409 status code indicates that a conflict occurred while processing the request. This could happen if the record is locked by another user or if the project is locked by an administrator.

{
  "message": "Record is locked for editing by another user.",
  "statusCode": 409,
  "code": "Conflict"
}

429 - Too Many Requests

If a user sends too many requests within a specified rate limiting timeframe, the API may return a 429 status code to prevent abuse or overload.

{
  "message": "The rate limit has been exceeded. Retry in X seconds.",
  "statusCode": 429,
  "code": "Rate limit exceeded"
}

Server Error Codes

These error codes generally indicate an issue on the server side of the Helix ALM REST API.

500 - Internal Server Error

The 500 status code is a generic error indicating that something went wrong on the server side. The error message included in the response may provide more details about the specific issue.

{
  "message": "The server experienced an error handling the request.",
  "statusCode": 500,
  "code": "Internal Server Error",
  "errorElementPath": "/{item type}/{index}"
}

503 - Service Unavailable

When the API server is unavailable or busy, a 503 status code is returned. This could be caused by throttling or a server lock due to high traffic or maintenance.

{
  "message": "The service is currently overloaded.",
  "statusCode": 503,
  "code": "Service Unavailable"
}

Conclusion

Understanding the various response and error codes in the Helix ALM REST API is essential for effective integration and troubleshooting. The API follows standard HTTP status code conventions, with success codes (200–206) indicating successful operations, client error codes (400–429) helping developers identify and fix issues in their requests, and server error codes (500–503) signaling server-side problems. Each response type is accompanied by detailed JSON objects that provide specific information about the operation's outcome or the nature of any errors encountered. By familiarizing themselves with these codes and their associated response formats, developers can build more robust applications that properly handle both successful operations and potential error scenarios when interacting with the Helix ALM platform.

Thank you for reading our article about the Helix ALM REST API, we hope it has helped explain some of the idiosyncrasies of the API. In part 5 we will look at constructing test steps for test cases.

Mecomis has over 20 years of experience with using Helix ALM, so if you have further questions about Helix ALM or a general inquiry, please contact us.

Author Of article : Mecomis Read full article

Working with Helix ALM REST API Part 4: Error and Response Codes