Responses (User Admin API)

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

All requests to User Admin 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. The first page of results is page 0.
  • 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": 0,
    "count": 25,
    "pageCount": 8,
    "totalCount": 200
  },
  "items": [
    ...
  ]
}

Response codes and errors

HTTP headers include:

HTTP/1.1 CODE MESSAGE
Content-Length: 7

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 User Admin 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: 4"
}

Invalid user name

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

{
  "message": "No user with that username could be found."
}

Error code 401 Unauthorized

The User Admin 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"
}

Error code 403 Forbidden

The User Admin 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 405 Method Not Allowed

The User Admin 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.