HTTP Status Codes
An even more complete list of HTTP status codes is documented here.
This HTTP status codes chart (takes a while to load) shows a decision tree to determine the usage of the correct HTTP status code.
2xx Success
The action was successfully received, understood, and accepted.
| Code | Description | Methods |
|---|---|---|
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. |
||
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. |
PUT only in case it is used to create a new document resource. |
|
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 Long-running tasks). A POST method may send 202 responses, but other methods should not. |
||
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. |
3xx Redirection
Further action must be taken in order to complete the request.
| Code | Description | Methods |
|---|---|---|
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. |
||
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”) 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. |
||
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 |
4xx Client Error
The request contains bad syntax or cannot be fulfilled.
| Code | Description | Method |
|---|---|---|
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. 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. |
||
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 |
||
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”) 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: |
||
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 |
||
409 (“Conflict”) should be used when a request conflicts with data on the server 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. |
||
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 |
||
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. |
||
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 |
||
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. |
5xx Server Error
The server failed to fulfill an apparently valid request.
| Code | Description | Methods |
|---|---|---|
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. |
||
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. |
||
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. |