Responses

The Control API returns standard HTTP status codes. Most endpoints return Json-Encoded responses. Some endpoints also return contextual HATEOAS links.

Codes in the 2xx range indicate success. Codes in the 4xx range indicate that the information provided for the request is invalid. Codes in the 5xx range indicate an error in the Control servers.

Errors

Note:

The Control API will in the future use the RFC 7807 Problem Details specification to indicate the failure of an API request.

HTTP Status Codes

Successful Requests (2xx)

Status Code Description
200 OK The request succeeded.
201 Created The request succeeded, and a new resource was created as a result.
202 Accepted The request has been received but not yet acted upon.
204 No Content The request succeeded, but without a response body.

Failed Requests (4xx)

Status Code Description
400 Bad Request The request was unacceptable.
401 Unauthorized The access token could not be authenticated.
401 Unauthorized The access token did not have permissions to the requested resource.
403 Forbidden The access token did not have permissions to perform the request.
404 Not Found The requested resource was not found.
405 Method Not Allowed The request method is known by the server but is not supported by the target resource. Example: PATCH.
406 Not Acceptable The server cannot use the client-request media type to return the response payload. (The request is most likely missing an Accept: application/json header.)
409 Conflict The request conflicts with the current state of the server. (Most likely due to a resource that already exists.)
415 Unsupported Media Type The media format of the requested data is not supported by the server. (The request is most likely missing a Content-Type: application/json header.)
429 Too Many Requests Too many requests in a given amount of time.

Server Error Responses (5xx)

Status Code Description
500 Internal Server Error An unhandled system or application error occurred.
501 Not Implemented The request method is not supported by the server and cannot be handled. (Most likely due to a feature that has not been implemented yet.)
503 Service Unavailable The server is not ready to handle the request. (The server might be overloaded or down for maintenance.)
504 Gateway Timeout This error response is given when the server is acting as a gateway and cannot get a response in time. (Most likely due to an unavailable service dependency.)