Vena API Troubleshooting Guide

Follow the steps in this troubleshooting guide to resolve errors with the Vena API. The steps provided in this guide apply to all endpoints in the Vena API. If you believe that your errors are particular to a specific endpoint, then please refer to the specific troubleshooting guides.

Initial Troubleshooting Steps

Check your authentication

If you are receiving a 401 Unauthorized error message, then the authentication user ID or key values you entered may be incorrect. Check that your authentication values are correct and try again.

Check your API parameters

If you are receiving a 404 Not Found error message, then you may be entering incorrect values for your API parameters. Visit the API reference page to find the values for your API parameters in Vena.

Check your data permissions

If you are receiving a 403 Forbidden error message, then you may not have the data permissions required to access the data you are requesting. For example, you may not have data permissions to access the model ID you are requesting. See this article for information on changing the data permissions applied to your authentication token.

Rate Limiting

If you are receiving a 429 Too Many Requests error, then you may have hit the rate limit that is applied to Vena’s API. The Export API has a rate limit applied for security and integrity reasons. If you are hitting the rate limit, you can consider increasing the pageSize query parameter.

Check your URL formatting

If you receive a 400 Bad Request error message, your URL request format may be incorrect. We recommend using the interactive request generator in the API Reference section to generate a URL in your programming language. This can help troubleshoot any formatting issues you may be experiencing.

Error Response Codes

Shown below are a few common error codes you may receive in the response when using the Vena API.

Troubleshooting the filters parameter in the Intersections endpoint

If you are using the filters parameter and receiving a 400 Bad Request error, troubleshooting the filters parameter may resolve your error. Learn more detailed information about the filters parameter in the Understanding the filters parameter article.

Multiple filter objects are provided for a single dimension

You cannot specify multiple filters for the same field. In the example below, the Year field is specified twice.

Example request:
/api/public/v1/models/{{modelID}}/intersections?filters=[{ "field": "Year", "eq": "2022"}, { "field": "Year", "eq": "2021" }]

Error response:
{ "error": { "type": "INVALID_PARAMETER", "title": "Invalid Parameter", "message": "Each dimension can only appear once in a query, try using In filter for: Year", "param": { "type": "QUERY", "path": [ "filters" ] } } }

While you can apply filters to multiple dimensions, the endpoint does not currently support multiple filters per dimension. For example, the following filters object would cause an error because multiple filters are specified for the Year dimension:
[{ "field": "Year", "eq": "2022"}, { "field": "Year", "eq": "2021" }]

To resolve the error, you can choose from the following options:

• Remove the additional filter objects for the dimension of interest
• Use multiple Intersections endpoint requests, each with its own filters parameter for the dimension of interest

Aggregate functionality isn’t supported

In the current Intersections endpoint, only bottom-level intersection values can be returned. None of the filter expressions support roll-up functionality to a specified parent member. For example, if you specify a parent-level member in the eq or in filter expression, you will not receive a roll-up of its children. Instead, you will receive a response with empty data.

If you are interested in aggregate functionality through our API, please reach out to Vena to have your use case considered for future releases.

Example request:
https://{hub}.vena.io/api/public/v1/models/{{modelID}}/intersections?filters=[{ "field": "Account","eq": "Revenue"}]

Example response:
{ "data": [], "metadata": { "nextPage": null, "recordsReturned": 0, "headers": [ "Value", ... ] } }

Referencing a dimension or a member that doesn’t exist

All member expression filters (using the mx field) must specify an existing dimension member in your data model. In the example below, the filter is attempting to find the Account named NotADimensionMember which doesn't exist.

Example request:
https://{hub}.vena.io/api/public/v1/models/{modelID}/intersections?filters=[{ "field": "Account","mx": {"bottomLevel": {"name": "NotADimensionMember"}}}]

Error response:
{ "error": { "type": "INVALID_PARAMETER", "title": "Invalid Parameter", "message": "The 'mx' filter for the field 'Account' is invalid. Missing Member \"NotADimensionMember\" in dimension Account (id=651628977392320512, num=1)", "param": { "type": "QUERY", "path": [ "filters", 0, "mx", "bottomLevel", "name" ] } } }

To resolve this error, double-check that all dimensions and member names referenced in the filters parameter exist in the data model.

Filters parameter capitalization issue or added to a URL request incorrectly

The filters parameter must be all lowercase and it must be added as a query parameter, not a header. If any part of thefilters parameter is capitalized, the filters will not be applied. In the example below, the filters parameter is mistakenly capitalized, so no values are filtered.

Example request:
https://{hub}.vena.io/api/public/v1/models/{modelID}/intersections?FILTERS=[{"field":"Year","eq":"2023"}]

Example response:
This response will not be filtered to only include 2023 values. The server will treat the above request as if there was no filters parameter at all.
{ "data": [ "1234.56" ], "metadata": { "nextPage": null, "recordsReturned": 0, "headers": [ "Value", ... ] } }

To resolve this error, refer to the API Reference to generate example requests that include the filters parameter.

Filters parameter syntax errors

Ensure the filter parameters doesn't have any misspelled fields and isn't missing any double quotes. Filters must be in JSON format, with double quotes around all keys and values. In the example below, the word field is misspelled and there are missing quotes.

Example request:
https://{hub}.vena.io/api/public/v1/models/{modelID}/intersections?filters=[{"fiellld":"invalid","missing: some quotes"}]

Error message:
{ "error": { "type": "INVALID_PARAMETER", "title": "Invalid Parameter", "message": "Unable to parse provided filters as JSON because: Unexpected character ('}' (code 125)): was expecting a colon to separate field name and value. Please check the syntax and try again.", "param": { "type": "QUERY", "path": [ "filters" ] } } }

To resolve this error, double-check that the filters parameter JSON notation is valid. Ensure that brackets and quotations are closed. More information on the correct syntax can be found in the Understanding the filters parameter article.

Further Assistance

If you were unable to resolve your issue using the documentation and would like further assistance, please contact Vena Support