REST API Response Codes
This document provides a description of the HTTP response codes returned by the REST API calls.
1. Overview
1.1. Success Codes
| Return Code | Result | Method |
|---|---|---|
| 200 | OK | GET, OPTIONS |
| 201 | Created | POST |
| 202 | Accepted | PUT |
| 204 | No content | GET, DELETE, OPTIONS |
1.2. Redirection Codes
| Return Code | Result | Method |
|---|---|---|
| 304 | Not Modified | GET, DELETE |
1.3. Client Error Codes
| Return Code | Result | Method |
|---|---|---|
| 400 | Bad Request | POST, GET, PUT, DELETE, OPTIONS |
| 401 | Unauthorized | POST, GET, PUT, DELETE, OPTIONS |
| 403 | Forbidden | POST, GET, PUT, DELETE, OPTIONS |
| 404 | Not Found | GET, PUT, DELETE |
| 405 | Method Not Allowed | POST, GET, PUT, DELETE, OPTIONS |
| 406 | Not Acceptable | POST, PUT |
| 409 | Conflict | POST, PUT |
| 410 | Gone | GET, PUT, DELETE, OPTIONS |
| 415 | Unsupported Media Type | POST |
| 421 | Misdirected Request | POST, GET, PUT, DELETE, OPTIONS |
| 422 | Unprocessable Content | GET |
| 423 | Locked | DELETE |
1.4. Server Error Codes
| Return Code | Result | Method |
|---|---|---|
| 500 | Internal Server Error | POST, GET, PUT, DELETE, OPTIONS |
2. Description
2.1. Success Codes
200 OK
Returned for successful GET, OPTIONS requests.
201 Created
Returned for successful POST requests.
202 Accepted
Returned for successful PUT requests.
204 No Content
Returned for successful GET, DELETE, OPTIONS requests.
GET 204 response means that the requested data is empty.
2.2. Redirection Codes
304 Not Modified
Returned when the requested resource has not been modified.
2.3. Client Error Codes
400 Bad Request
The request is a valid URL; but the data being passed is not valid JSON, in regards to objects, array and JSON data values.
This effectively means that the json_decode() failed to parse the data passed.
This is also the case where no keys are provided, if readonly keys (for PUT) exist or additional properties are provided when they shouldn’t be.
401 Unauthorized
Returned when user credentials are not valid.
403 Forbidden
Returned when an attempt to delete or modify a readonly attribute (not complex object) is made.
404 Not Found
Returned when the resource being requested does not exist. This should be on assets (name) and entities (id); and also with keys/permissions when additionalProperties is false, when additionalProperties is true; they should be assumed to be a string value.
405 Method Not Allowed
Returned when a request on a specific method and URI doesn’t exist. This is on the root ‘/’ route and any POST, GET, PUT, DELETE and OPTIONS request where there is no specific handler defined. Doing a PUT or DELETE on a collection is an example of this; it will always fail, regardless how many times it is attempted.
406 Not Acceptable
Returned when the JSON is valid, but the data does not match the requirements of the schema (“bad data”).
Examples include: required but missing properties, non-unique elements within entity (arrays), failed regex validation, bad numeric properties (violation of min, max, multipleof etc).
The request can be updated with correct information and resent; it will then be accepted.
409 Conflict
Returned when an asset or entity with the same high level unique properties exists (non-unique).
Note that at the sub-object level, uniqueness is controlled by the schema validation (resulting in a 406 error response).
The high level attributes or the other resource must be deleted in order for the request to succeed.
410 Gone
Returned when an object has been orphaned (exists, but not available) - will only happen for entities, as assets do not have a concept of being orphaned. when the entity is restored (unorphaned); the request will function as nromal.
415 Unsupported Media Type
Returned when the asset file doesn’t meet the criteria (image, hex or firmware file).
421 Misdirected Request
Returned if pre-requisits do not exist with nested entities or assets; for example when tenant_id is missing when dealing with tenant based objects.
The URI handler will prevent such cases from ever occuring, so this error code may never be seen by the developer or end user.
422 Unprocessable Content
Returned in response to a GET request on a device object if an installer is requested, but no installer sketch is defined.
423 Locked
Returned if an attempt to DELETE a resource that is currently in use is made.
2.4. Server Error Codes
500 Internal Server Error
Returned if the server encounters an error.