Responses (Agents API)

Owned by Helen Griffith
Last updated: Feb 15, 2022
2 min read

All requests to the Agents 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 OK code with a JSON object in the response body. For specific details on the payload of each endpoint response, see the API reference (Agents API).

Response codes and errors

Error code 400 Bad Request

The Agents API returns 400 Bad Request in response to an invalid request.

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:

{
    "error": {
        "code": "ApiVersionUnspecified",
        "message": "An API version is required, but was not specified."
    }
}

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:

{
    "error": {
        "code": "UnsupportedApiVersion",
        "message": "The HTTP resource that matches the request URI 'https://{$$.env.region}.api.newvoicemedia.com/agents/87f2c044-1c71-8167-32af-184c17baf612/presence' does not support the API version '2'."
    }
}

Invalid GUID

{
  "message": "The request is invalid."
}

PresenceId missing

{
  "status": 400,
  "title": "One or more validation errors occurred.",
  "errors": [
    {
      "message": "The PresenceId field is required.",
      "path": "presenceId"
    }
  ]
}

Query limit

{
  "status": 400,
  "title": "Query limit",
  "detail": "Request exceeded maximum number for users of 50 in one query."
}

Error code 401 Unauthorized

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

{
  "message": "Authorization has been denied for this request."
}

Error code 403 Forbidden

The Agents API returns 403 Forbidden in response to a request that is not authorized. This error is generally caused by a token that is missing one or more required scopes.

{
  "status": 403,
  "title": "Insufficient scopes.",
  "detail": "Authorization has been denied for this request."
}

Error code 404 Not Found

The Agents API returns 404 Not Found in response to a request for an item that was not found. You may have requested an user or presence that doesn’t exist.

User not found

{
  "status": 404,
  "title": "Resource is missing.",
  "detail": "User cannot act as an agent or does not exist.",
  "correlationId": "CorrelationId header not found."
}

Presence not found

{
  "status": 404,
  "title": "Resource is missing.",
  "detail": "Presence with GUID: 7e8a129d-14e6-4f84-bc0b-afc3f2452b68 does not exist",
  "correlationId": "CorrelationId header not found."
}

Invalid GUID

Invalid GUIDs may result in a 404 Not Found or will simply be skipped depending on the endpoint used.