Troubleshooting

The following section describes common troubleshooting scenarios and HTTP status codes.

HTTP status codes

The TM1 REST API uses standard HTTP/1.1 protocol to communicate between the client and the server. This means that requests and responses follow the conventions for this protocol, in addition to the rules identified by the OData specification. For specific details about the common response status codes and their meaning, see Section 9 of OData Version 4.0 Part 1: Protocol.

Response status codes from the server typically fall into one of the following categories:
  • 2xx range typically indicates a successful operation
  • 3xx range identifies redirection while 304 is returned when the client issues a GET request and content has not changed when using If-Match or If-None-Match
  • 4xx range is generally an error in the client request, such as a malformed request
  • 5xx status is likely an error on the part of the TM1 server

In addition to HTTP status codes, you might receive an error message from the TM1 server that identifies more details. For example, if you try to create an entity when an entity with the same name exists, the server issues a 400 status code, and the following message in JSON format is included in the response body:

   {"error":{"code":"","message":"A dimension named my_new_department2 already exists."}}

The error message can provide additional information to help you diagnose the error.

405 Method Not Allowed

Trying to perform an operation on an entity when the operation is invalid for that context results in a 405 error from the server. In the response header, a list of valid operations is listed in an Allow header:

Status Code: 405
Content-Type: text/plain
Content-Length: 0
Connection: keep-alive
Allow: GET, POST, PATCH, DELETE, OPTIONS
OData-Version: 4.0

In this example, only GET, POST, PATCH, DELETE, or OPTIONS is allowed on the entity that is specified in the request.

Monitoring HTTP traffic on the client or server

To help you troubleshoot issues, you can use several tools to debug your issue. HTTP traffic monitoring tools, and REST or web development plug-ins for common web browsers can provide extra details about the requests and responses between the client and server that can help you troubleshoot.

It might also be possible to configure an HTTP monitoring tool as a proxy on the server to monitor all traffic.

Invalid JSON payload (400)

If you include JSON content in a POST request, you receive an error from the server if the payload contains invalid JSON syntax:

   {"error":{"code":"","message":"Invalid JSON:"}}

Use a validation tool to ensure that your JSON payload is correctly formatted before you submit a request.

For more information, use the following resources: