REST API Response status codes

The common HTTP/1.1 response Status Codes are listed below

200 (“OK”)

• Should be used to indicate nonspecific success
• Must not be used to communicate errors in the response body

201 (“Created”)

• Must be used to indicate successful resource creation
• A REST API responds with the 201 status code whenever a collection creates, or a store adds, a new resource at the client’s request.

202 (“Accepted”)

• Must be used to indicate successful start of an asynchronous action
• A 202 response indicates that the client’s request will be handled asynchronously.
• This response status code tells the client that the request appears valid, but it still may have problems once it’s finally processed.

204 (“No Content”)

• Should be used when the response body is intentionally empty
• The 204 status code is usually sent out in response to a PUT, POST, or DELETE request, when the REST API declines to send back any status message or representation in the response message body.
• An API may also send 204 in conjunction with a GET request to indicate that the requested resource exists, but has no state representation to include in the body

301 (“Moved Permanently”)

• Should be used to relocate resources
• The 301 status code indicates that the REST API’s resource model has been significantly redesigned and a new permanent URI has been assigned to the client’s requested resource.
• The REST API should specify the new URI in the response’s Location header.

302 (“Found”)

• Should not be used .
• HTTP 1.1 introduced status codes 303 (“See Other”) and 307 (“Temporary Redirect”), either of which should be used instead of 302.

303 (“See Other”)

• Should be used to refer the client to a different URI
• A 303 response indicates that a controller resource has finished its work, but instead of sending a potentially unwanted response body, it sends the client the URI of a response resource.
• Generally speaking, the 303 status code allows a REST API to send a reference to a resource without forcing the client to download its state. Instead, the client may send a GET request to the value of the Location header. ( Sort of Reference Type)

304 (“Not Modified”)

• Should be used to preserve bandwidth.
• A 304 Not Modified message is an HTTP response status code indicating that the requested resource has not been modified since the previous transmission, so there is no need to retransmit the requested resource to the client.
• In effect, a 304 Not Modified response code acts as an implicit redirection to a cached version of the requested resource.(Sort of Cache)

307 (“Temporary Redirect”)

• Should be used to tell clients to resubmit the request to another URI
• HTTP/1.1 introduced the 307 status code to reiterate the originally intended semantics of the 302 (“Found”) status code.
• A 307 response indicates that the REST API is not going to process the client’s request. Instead, the client should resubmit the request to the URI specified by the response message’s Location header.

400(“Bad Request”)

• May be used to indicate nonspecific failure
• 400 is the generic client-side error status, used when no other 4xx error code is appropriate.

401(“Unauthorized”)

• Must be used when there is a problem with the client’s credentials

403(“Forbidden”)

• Should be used to forbid access regardless of authorization state
• A 403 error response indicates that the client’s request is formed correctly, but the REST API refuses to honor it.
• A 403 response is not a case of insufficient client credentials; that would be 401 (“Unauthorized”).
• REST APIs use 403 to enforce application-level permissions. (Example : A client may be authorized to interact with some, but not all of a REST API’s resources. If the client attempts a resource interaction that is outside of its permitted scope, the REST API should respond with 403.)(Sort of Authorization)

404(“Not Found”)

• Must be used when a client’s URI cannot be mapped to a resource

405(“Method Not Allowed”)

• Must be used when the HTTP method is not supported while a controller resource might allow GET and POST, but not PUT or DELETE.
• A 405 response must include the Allow header, which lists the HTTP methods that the resource supports. For example: Allow: GET, POST

406(“Not Acceptable”)

• Must be used when the requested media type cannot be served
  (For example, a client request for data formatted as application/xml will receive a 406 response if the API is only willing to format data as application/json.)

409(“Conflict”)

• Should be used to indicate a violation of resource state (For example, you may get a 409 error if you try to upload a file to the Web server which is older than the one already there - resulting in a version control conflict.)

412(“Precondition Failed”)

• Should be used to support conditional operations
• The 412 error response indicates that the client specified one or more preconditions in its request headers, effectively telling the REST API to carry out its request only if certain conditions were met.
• A 412 response indicates that those conditions were not met, so instead of carrying out the request, the API sends this status code.

415(“Unsupported Media Type”)

• Must be used when the media type of a request’s payload cannot be processed
• The 415 error response indicates that the API is not able to process the client’s supplied media type, as indicated by the Content-Type request header.
• Use 406 if can't output in the expected format and use 415 if you don't support the input format. ( For example, a client request including data formatted as application/xml will receive a 415 response if the API is only willing to process data formatted as application/json. )

500(“Internal Server Error”)

• Should be used to indicate API malfunction 500 is the generic REST API error response.
• Most web frameworks automatically respond with this response status code whenever they execute some request handler code that raises an exception.
• A 500 error is never the client’s fault and therefore it is reasonable for the client to retry the exact same request that triggered this response, and hope to get a different response.