REST APIs use HTTP response codes to communicate status information. An API consumer should be able to inspect the HTTP response code and understand the status of its request.

Required Response Codes

The following response codes must be used when responding to requests.

Table 6. Response and Status Codes

HTTP Response CodeNameReason(s)
200OK

Returned after a successful operation when a response contains a body.

201Created

Returned after a successful POST. The response from a POST will also include a location in the header pointing to the newly added resource. A POST response will not contain a body.

204No Content

Returned when the server has fulfilled the request, but does not return an entity body.

304Not Modified

Returned when the client includes the “If-None-Match” header containing the requested resource’s last known entity tag.

400

Bad Request

Returned if the request is malformed. The body of the response may contain a descriptive error message.

401

Unauthorized

Returned if the access token is invalid. The response will not contain a body.

403

Forbidden

Returned when the server is refusing to fulfill a request in situations such as the requesting client is not authorized to execute the requested action on the requested resource

404

Not Found

Returned if a resource is not found. The response will not contain a body.

409

Conflict

Returned when there is any type of referential integrity violation.

412

Precondition Failed

Returned if an “If-Match” header pre-condition fails.

500

Internal Server Error

Returned if the server encountered an unexpected error during the operation.

Errors

If an error occurs on the server, a 500 (Internal Server Error) code must be returned. A message in the body, containing the error details, should be provided. However, raw errors generated by system failures must not returned to the client to avoid inadvertently exposing any sensitive data or technical information to an attacker. 

For example:


{ 
    “code”: 500, “type”: “Internal Server Error”, “message”: “Unable to communicate with database”
}