API Status and Error Codes

Learn about Visier API call status codes and errors.

Status codes

Visier uses standard HTTP response codes to inform you of the success or failure of an API request.

Codes are grouped into several categories, summarized in the following list:

• 2xx: A successful API request.
• 4xx: An error occurred due to the provided request parameters.
• 5xx: An error occurred with Visier’s servers.

The following table describes each of the possible codes.

Errors

If an error occurs, more detail is available in the response payload. For any unexpected issues, please quote the RCI code and localized message when contacting Visier Support.

The value associated with the message key indicates the nature of the error. Ensure that common issues are managed within your code.

Response

Sample response

In this example, the error indicates that the query is invalid due to unspecified time intervals. To fix this error, determine the appropriate time interval and take the appropriate corrective action.

{
    "localizedMessage": "Bad request: Job Id [{jobId}] is not valid",
    "message": "",
    "rci": "RCIY7770027",
    "code": "VSE_BADREQUEST",
    "userError": true
}

Troubleshoot API errors

API error messages provide the information you need to investigate and solve the issue. When troubleshooting, read the localizedMessage or message field in the error response to learn what went wrong and potential next steps. In this section, learn about the most common API errors and how to resolve them.

Invalid IDs

Many API calls require you to provide the unique identifiers of the objects or tenants you're requesting through the API, such as tenant codes, metric names, usernames, and permission IDs. You might receive an invalid ID error message in the following scenarios: 

• The API request contains a typo or incorrect name.
• You're creating or updating an object ID and the specified ID doesn't adhere to the allowed characters or character limit.

To resolve this error, check the API request input and adjust the ID.

Object already exists

Similar to invalid IDs, this error occurs if you try to create a new object with the same ID as an existing object, such as creating a new user with an existing username. IDs must be unique.

To resolve this error, check the API request input and adjust the ID.

Insufficient profile capabilities

Actions in Visier are guarded by profiles, permissions, toggles, and subscriptions. Profile capabilities guard the actions that users can make in Studio, such as user and tenant management, data upload, and changes to the analytic model. An insufficient profile capability error happens when the API user makes an API request that is not allowed based on the user's current profile capabilities.

To resolve this error, contact your administrator to request the required profile capabilities. For more information about profiles, see Profile Capabilities.

Insufficient analytic capabilities

Actions in Visier are guarded by profiles, permissions, toggles, and subscription. Analytic capabilities are part of permissions, which guard the actions that users can make in the solution, such as using Vee. An insufficient analytic capability error happens when the API user makes an API request that is not allowed based on the user's current permissions.

To resolve this error, contact your administrator to request the required analytic capabilities. For more information about permissions, see Permission Management.

Insufficient data access

Actions in Visier are guarded by profiles, permissions, toggles, and subscription. Data access is part of permissions, which guard the data that users are allowed to view. An insufficient data access error happens when the API user makes an API request for data that the user is not allowed to view based on the user's current permissions.

To resolve this error, contact your administrator to request the required data access. For more information about permissions, see Permission Management.

Request data is malformed

Visier APIs accept request data in the format specified by the Content-Type header. A request data is malformed error happens if the API request input isn't in the correct format or if the amount of data in the API request input exceeds the maximum limit.

To resolve this error, check the format of your data in the API request input for correct format. If the format is correct, the input may include too much data. Check that the data in the API request input doesn't exceed the maximum limit. For more information about the Content-Type header, see API Headers.

Expected data version is not available

In Visier, processed data is associated with unique data versions. An expected data version is not available error happens if the data version is out-of-date or not available in production.

To resolve this error, generate a new data version and try the API request after the data version is published to production. For more information about data versions, see Data Versions.