Error messages

The REST API uses HTTP status codes to signal error conditions, which fall into two broad categories:

4xx: client errors (missing credentials, invalid format, etc.)
5xx: server errors (internal server issues)

In addition to status codes, the API returns JSON payloads for error conditions in json format like:

400 Bad Request
Content-Length: <length>
Content-Type: application/json;
{
  "errors:" [{
    "code": "BAD_REQUEST",
    "message": "invalid request data given",
    "detail": "Either a valid API key or JWT token must be given to identify the account."
  }]
}

The code is the HTTP status code, the message provides a brief human-readable description for developers and the detail offers a detailed explanation of the error along with potential ways to fix it.

Error Types

400: INVALID REQUEST

Request failed because it doesn’t contain valid request data, for example: invalid API key or JWT token. Please log into Uniserv CONNECT and check your API key.

400 Bad Request
Content-Length: <length>
Content-Type: application/json;
{
  "errors:" [{
    "code": "BAD_REQUEST",
    "message": "invalid request data given",
    "detail": "Either a valid API key or JWT token must be given to identify the account."
  }]
}

401: DOCKER DOWNLOADS - AUTHENTICATION REQUIRED

A Basic Authentication must be specified for downloading docker images. Please log into Uniserv CONNECT and check your API key.

401 Unauthorized
WWW-Authenticate: Basic realm="docker-registry"
Content-Length: <length>
Content-Type: application/json;
{
  "errors:" [{
    "code": "UNAUTHORIZED",
    "message": "authentication required",
    "detail": "Missing basic auth credentials; expected username 'uniserv' with API key as password"
  }]
}

401: REFERENCE DATA | SOFTWARE - AUTHENTICATION REQUIRED

Request failed due to missing valid authentication for the requested resource. Possible reasons are:

The Authorization header has not been set in the request.

401 Unauthorized
Content-Length: <length>
Content-Type: application/json;
{
  "errors:" [{
    "code": "UNAUTHORIZED",
    "message": "authentication required",
    "detail": "Missing Authorization-Header"
  }]
}

401: REFERENCE DATA | SOFTWARE - INVALID AUTHENTICATION

Request failed due to missing valid authentication for the requested resource. Possible reasons are:

A Bearer Token with an API key was not set in the Authorization Header
JWT token is either invalid or expired

401 Unauthorized
Content-Length: <length>
Content-Type: application/json;
{
  "errors:" [{
    "code": "UNAUTHORIZED",
    "message": "authentication required",
    "detail": "Invalid username or password or API key or token"
  }]
}

403: ACCESS DENIED

403 Forbidden
Content-Length: <length>
Content-Type: application/json;
{
  "errors:" [{
    "code": "FORBIDDEN",
    "message": "requested access to the resource is forbidden",
    "detail": "The user has no permission to access the resource"
  }]
}

404: RESOURCE DOES NOT EXIST

404 Not Found
Content-Length: <length>
Content-Type: application/json;
{
   "errors": [
      {
         "code": "NOT_FOUND",
         "message": "requested resource does not exist",
         "detail": "Please check the name and the version of the resource you have requested"
      }
   ]
}

404: RELEASE-ALIAS IS NOT SUPPORTED

404 Not Found
Content-Length: <length>
Content-Type: application/json;
{
   "errors": [
      {
         "code": "NOT_FOUND",
         "message": "release-alias does not exist",
         "detail": "For the requested resource release-alias is not supported"
      }
   ]
}

404: LATEST-ALIAS IS NOT SUPPORTED

404 Not Found
Content-Length: <length>
Content-Type: application/json;
{
   "errors": [
      {
         "code": "NOT_FOUND",
         "message": "latest-alias does not exist",
         "detail": "For the requested resource latest-alias is not supported"
      }
   ]
}

500: INTERNAL SERVER ERROR

500 Internal Server Error
Content-Length: <length>
Content-Type: application/json;
{
   "errors": [
      {
         "code": "INTERNAL_SERVER_ERROR",
         "message": "internal server error",
         "detail": "Parts of the system are currently not available. Try again later."
      }
   ]
}