Responses (Insights Stats API)

Owned by Helen Griffith
Last updated: Jan 09, 2024
3 min read

All requests to Insights Stats API endpoints return standard HTTP headers, including the response status code, and a response body in JSON format.

Success response code and parameters

Successful requests return a 200 Success code with a JSON object in the response body.

Responses from endpoints that can return multiple resources contain a meta item in the response body. The meta item appears at the start of the response and contains the following parameters:

  • page. The current requested page.
  • count. The count of the items returned for a specific request. If we have the same or more as the limit the value matches the same value.
  • pageCount. The number of pages that result from the specified limit.
  • totalCount. The total number of items that we can retrieve from the API.
{
  "meta": {
    "page": 1,
    "count": 25,
    "pageCount": 8,
    "totalCount": 200
  },
  "items": [
    ...
  ],
  "upTo": "2019-12-19T14:18:32.395Z"
}

The response body also contains the upTo parameter. The upTo parameter appears at the end of the response, and represents the time of the request. This time is useful if you are polling the API as you know exactly when the previous request retrieved data from Vonage Contact Center.

Response codes and errors

HTTP headers include:

HTTP/1.1 CODE MESSAGE
Cache-Control: max-age=5, must-revalidate, private

The response body contains either the requested information or an error message:

{
    "message":"MESSAGE"
}

Errors are returned using standard HTTP error code syntax, such as 400 Bad Request. Additional information is included in the body of the return call in JSON format, usually in the following format:

{
  "message": "Appropriate 400 error message"
}

Error code 400 Bad Request

The Insights Stats API returns 400 Bad Request in response to an invalid request. You may have provided a DateTime value in the wrong format or a number value outside of the allowed limits.

Missing API version

If you do not provide the required API version in the Accept header, you will receive the following message in addition to the 400 error code:

{
  "message": "Version missing from Accept header!"
}

Invalid API version

If you provide an invalid API version in the Accept header, you will receive the following message in addition to the 400 error code:

{
  "message": "Invalid api-version! Valid values: 1,2"
}

Missing required parameter

If you do not provide a required value for a parameter, you will receive the following message in addition to the 400 error code:

{
  "message": "child \"start\" fails because [\"start\" is required]"
}

Invalid DateTime value

If you provide a DateTime value in a parameter in the wrong format, you will receive the following message in addition to the 400 error code:

{
  "message": "child \"start\" fails because [\"start\" must be a valid ISO 8601 date]"
}

Invalid GUID

If you provide an invalid GUID, you will receive the following message in addition to the 400 error code:

{
  "message": "child \"guid\" fails because [\"guid\" must be a valid GUID]"
}

Error code 401 Unauthorized

The Insights Stats API returns 401 Unauthorized in response to an invalid, expired or missing bearer access token.

Missing token

If you do not provide your bearer access token, you will receive the following message in addition to the 401 error code:

{
  "error_description": "The access token is missing",
  "error": "invalid_request"
}

Invalid token

If you provide an invalid or expired bearer access token, you will receive the following message in addition to the 401 error code:

{
  "error_description": "The access token is invalid or has expired",
  "error": "invalid_token"
}

Missing scope

If your client credentials contain the required scope, but your bearer access token does not, you will receive the following message in addition to the 401 error code:

{
    "message": "Unauthorized"
}

Error code 403 Forbidden

The Insights Stats API returns 403 Forbidden in response to a request that is not authorized.

Insufficient scope

If you can authenticate with the API but do not have access to the specific resource you request, you will receive the following message in addition to the 403 error code:

{
  "message": "Insufficient scope"
}

Error code 404 Not Found

The Insights Stats API returns 404 Not Found in response to a request for an item that was not found. You may have requested an interaction that doesn’t exist.

If you request an item that is not found, you will receive the following message in addition to the 404 error code:

{
  "message": "Not Found"
}

Error code 405 Method Not Allowed

The Insights Stats API returns 405 Method Not Allowed in response to a call to a method that is not allowed. For example a POST method.

If you send a request using a method that is not allowed, you will receive the following message in addition to the 405 error code:

{
  "message": "Method Not Allowed"
}

Error code 500 Internal Server Error

An internal server error occurred.