Responses (Insights Stats API)
Response format
All responses from the Insights Stats API return standard HTTP headers and a response body in JSON format.
The response header includes an HTTP status code and message:
HTTP/1.1 200 OK
Cache-Control: max-age=5, must-revalidate, privateUse the status code to determine the outcome of the request. A 200 status code indicates that the request succeeded and the response body contains the requested data. A 4xx or 5xx status code indicates an error; the response body contains a message field describing the error:
{ "message": "Error description" }Some error codes return a different response body structure; see the Error code 401 Unauthorized section for an example.
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:
Field | Description |
|---|---|
| The current requested page. |
| The number of items returned for this page. If the result set is equal to or larger than the page limit, this value matches the limit. |
| The total number of pages that result from the specified limit. |
| The total number of items available across all pages. |
{
"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.
Error code 400 Bad Request
The Insights Stats API returns 400 Bad Request in response to an invalid request. The following table describes the scenarios that return a 400 error and the corresponding response message.
Scenario | Cause | Response message |
|---|---|---|
Missing API version | The | {
"message": "Version missing from Accept header!"
} |
Invalid API version | The | {
"message": "Invalid api-version! Valid values: 1,2"
} |
Missing required parameter | A required parameter value is not provided. | {
"message": "child \"start\" fails because [\"start\" is required]"
} |
Invalid DateTime value | A DateTime parameter value is not in ISO 8601 format. | {
"message": "child \"start\" fails because [\"start\" must be a valid ISO 8601 date]"
} |
Invalid GUID | A GUID parameter value is not a valid GUID. | {
"message": "child \"guid\" fails because [\"guid\" must be a valid GUID]"
} |
The parameter name in the response message reflects the name of the failing parameter. The examples above use start and guid for illustration.
Error code 401 Unauthorized
The Insights Stats API returns 401 Unauthorized in response to an invalid, expired, or missing bearer access token. The following table describes the scenarios that return a 401 error and the corresponding response body.
Scenario | Cause | Response body |
|---|---|---|
Missing token | A bearer access token is not included in the request. | {
"error_description": "The access token is missing",
"error": "invalid_request"
} |
Invalid token | The bearer access token is invalid or has expired. | {
"error_description": "The access token is invalid or has expired",
"error": "invalid_token"
} |
Missing scope | The client credentials include the required scope, but the bearer access token does not. This can occur if the token was requested with a different scope from the one defined in the client credentials. | {
"message": "Unauthorized"
} |
Error code 403 Forbidden
The Insights Stats API returns 403 Forbidden in response to a request that is not authorized.
Scenario | Cause | Response body |
|---|---|---|
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 using 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 InternalError status indicates that a processing error occurred during the interaction. The data returned for the interaction may be incomplete.
InternalError status and incomplete interaction data
An Internal Server Error can occur for several reasons, including an unusually complex call plan that generates a large number of routing events, for example, a plan with a looping structure that routes the same interaction repeatedly through queues or data connectors. When this occurs, the API stops updating the interaction data to prevent further errors.
If you encounter interactions with this status, review your call plan configuration for loops or repetitive routing steps. For more information, see the FAQ (Insights Stats API).