Status codes

The full list of HTTP status codes is documented here.

In order to conform to the REST uniform service contract, REST services should stick to this reduced list of status codes.

This HTTP status codes chart (takes a while to load) shows a decision tree to determine the usage of the correct HTTP status code.

1xx Informational

Request received, continuing process.

2xx Success

The action was successfully received, understood, and accepted.

Code	Description	Methods
200 OK	200 (“OK”) should be used to indicate nonspecific success In most cases, 200 is the code the client hopes to see. It indicates that the REST API successfully carried out whatever action the client requested, and that no more specific code in the 2xx series is appropriate. Unlike the 204 status code, a 200 response should include a response body.	GET, HEAD, PUT, PATCH, DELETE, OPTIONS
201 Created	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. The response body may be empty or contain a partial or full representation of the new resource. There may also be times when a new resource is created as a result of some custom POST action, in which case 201 would also be an appropriate response.	POST PUT only in case it is used to create a new document resource.
202 Accepted	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. A 202 response is typically used for actions that take a long while to process (see ???). A POST method may send 202 responses, but other methods should not.	POST
204 No Content	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, PATCH or DELETE request, when the REST API declines to send back any status message or representation in the response message’s body.	POST, HEAD, PUT, PATCH, DELETE, OPTIONS

3xx Redirection

Further action must be taken in order to complete the request.

Code	Description	Methods
301 Moved Permanently	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.	All: GET, HEAD, POST, PUT, PATCH, DELETE, OPTIONS
303 See Other	303 (“See Other”) should be used to refer the client to a different URI 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. It can be used when a long-running action has finished its work, but instead of sending a potentially unwanted response body, it sends the client the URI of a response resource. This can be the URI of a temporary status message, or the URI to some already existing, more permanent, resource.	All methods are acceptable. Mostly used with POST.
304 Not Modified	304 (“Not Modified”) should be used to preserve bandwidth This status code is similar to 204 (“No Content”) in that the response body must be empty. The key distinction is that 204 is used when there is nothing to send in the body, whereas 304 is used when there is state information associated with a resource but the client already has the most recent version of the representation. This status code is used in conjunction with conditional HTTP requests.	GET, HEAD
307 Temporary Redirect	307 (“Temporary Redirect”) should be used to tell clients to resubmit the request to another URI 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. A REST API can use this status code to assign a temporary URI to the client’s requested resource. For example, a `307` response can be used to shift a client request over to another host.	All: GET, HEAD, POST, PUT, PATCH, DELETE, OPTIONS

4xx Client Error

The request contains bad syntax or cannot be fulfilled.

Code	Description	Method
400 Bad Request	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.	All: GET, HEAD, POST, PUT, PATCH, DELETE, OPTIONS
401 Unauthorized	401 (“Unauthorized”) must be used when there is a problem with the client’s credentials. A 401 error response indicates that the client tried to operate on a protected resource without providing the proper authorization. It may have provided the wrong credentials or none at all.	All: GET, HEAD, POST, PUT, PATCH, DELETE, OPTIONS
403 Forbidden	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”)`.	All: GET, HEAD, POST, PUT, PATCH, DELETE, OPTIONS
404 Not Found	404 (“Not Found”) must be used when a client’s URI cannot be mapped to a resource. The 404 error status code indicates that the REST API can’t map the client’s URI to a resource.	All: GET, HEAD, PUT, PATCH, DELETE, OPTIONS, POST (if parent resource not found)
405 Method Not Allowed	405 (“Method Not Allowed”) must be used when the HTTP method is not supported. The API responds with a 405 error to indicate that the client tried to use an HTTP method that the resource does not allow. For example, when a PUT or POST action is performed on a read-only resource supporting only GET and HEAD. A 405 response must include the Allow header, which lists the HTTP methods that the resource supports. For example: `Allow: GET, POST`	All: GET, HEAD, POST, PUT, PATCH, DELETE, OPTIONS
406 Not Acceptable	406 (“Not Acceptable”) must be used when the requested media type cannot be served The 406 error response indicates that the API is not able to generate any of the client’s preferred media types, as indicated by the `Accept` request header. 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`.	All: GET, HEAD, POST, PUT, PATCH, DELETE, OPTIONS
409 Conflict	409 (“Conflict”) should be used when a request conflicts with the current state of the target resource The 409 error response tells the client that they tried to put the REST API’s resources into an impossible or inconsistent state. For example, a REST API may return this response code when a client tries to DELETE a non-empty store resource.	POST, PUT, PATCH, DELETE
412 Precondition Failed	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. Only use for conditional HTTP requests, not constraints expressed in the HTTP payload. Use `409 Conflict` instead.	POST, PUT, PATCH, DELETE
413 Payload Too Large	413 (“Payload Too Large”) should be used when a request is refused because its payload is too large The 413 error response indicates that the request is larger than the server is willing or able to process.	POST, PUT, PATCH
415 Unsupported Media Type	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. 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.	All: GET, HEAD, POST, PUT, PATCH, DELETE, OPTIONS
429 Too Many Requests	429 (“Too Many Requests”) should be used to indicate that the user has sent too many requests in a given amount of time. The response representations SHOULD include details explaining the condition, and MAY include a Retry-After header indicating how long to wait before making a new request. Note that this specification does not define how the origin server identifies the user, nor how it counts requests. Responses with the 429 status code MUST NOT be stored by a cache.	All: GET, HEAD, POST, PUT, PATCH, DELETE, OPTIONS

5xx Server Error

The server failed to fulfill an apparently valid request.

Code	Description	Methods
500 Internal Server Error	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.	All: GET, HEAD, POST, PUT, PATCH, DELETE, OPTIONS
502 Bad Gateway	The 502 ("Bad Gateway") status code indicates that the server, while acting as a gateway or proxy, received an invalid response from an inbound server it accessed while attempting to fulfill the request.	All: GET, HEAD, POST, PUT, PATCH, DELETE, OPTIONS
503 Service Unavailable	503 (“Service Unavailable”) indicates that the server is currently unable to handle the request due to a temporary overload or scheduled maintenance, which will likely be alleviated after some delay. The server MAY send a Retry-After header field to suggest an appropriate amount of time for the client to wait before retrying the request.	All: GET, HEAD, POST, PUT, PATCH, DELETE, OPTIONS

500 Internal Server Error

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.

All: GET, HEAD, POST, PUT, PATCH, DELETE, OPTIONS

502 Bad Gateway

The 502 ("Bad Gateway") status code indicates that the server, while acting as a gateway or proxy, received an invalid response from an inbound server it accessed while attempting to fulfill the request.

All: GET, HEAD, POST, PUT, PATCH, DELETE, OPTIONS

503 Service Unavailable

503 (“Service Unavailable”) indicates that the server is currently unable to handle the request due to a temporary overload or scheduled maintenance, which will likely be alleviated after some delay.

The server MAY send a Retry-After header field to suggest an appropriate amount of time for the client to wait before retrying the request.

All: GET, HEAD, POST, PUT, PATCH, DELETE, OPTIONS

Status codes for each method

Code	GET	HEAD	PUT	POST	PATCH	DELETE	OPTIONS
200 OK	X	X	X	X (controller only)	X	X	X
201 Created	-	-	X (creation only)	X	-	-	-
202 Accepted	-	-	-	X	-	-	X
204 No Content	-	X	X	X	X	X	-
301 Moved Permanently	X	X	X	X	X	X	X
303 See Other	-	-	-	X	-	-	-
304 Not Modified	X	X	-	-	-	-	-
307 Temporary Redirect	X	X	X	X	X	X	X
400 Bad Request	X	X	X	X	X	X	X
401 Unauthorized	X	X	X	X	X	X	X
403 Forbidden	X	X	X	X	X	X	X
404 Not Found	X	X	X	X	X	X	X
405 Method Not Allowed	X	X	X	X	X	X	-
406 Not Acceptable	X	X	X	X	X	X	X
409 Conflict	-	-	X	X	X	X	-
412 Precondition Failed	-	-	X	X	X	X	-
413 Payload Too Large	-	-	X	X	X	-	-
415 Unsupported Media Type	X	X	X	X	X	X	X
429 Too Many Requests	X	X	X	X	X	X	X
500 Internal Server Error	X	X	X	X	X	X	X
502 Bad Gateway	X	X	X	X	X	X	X
503 Service Unavailable	X	X	X	X	X	X	X