REST API - HTTP Status Codes

In this article, we will learn about commonly used HTTP status codes in RESTful APIs.

Learn about RESTful APIs at JavaGuides

HTTP Status Codes

For every HTTP request, the server returns a status code indicating the processing status of the request. Understanding these status codes will help us design better RESTful web services.

1xx Informational

This series of status codes indicates informational content. This means that the request is received, and processing is ongoing. Here are the frequently used informational status codes:

100 Continue: This code indicates that the server has received the request header, and the client can now send the body content. The client first makes a request (with the Expect: 100-continue header) to check whether it can start with a partial request. The server can then respond either with 100 Continue (OK) or 417 Expectation Failed (No), along with an appropriate reason.
101 Switching Protocols: This code indicates that the server is OK for a protocol switch request from the client.
102 Processing: This code is an informational status code used for long-running processing to prevent the client from timing out. This tells the client to wait for the future response, which will have the actual response body.

2xx Success

This series of status codes indicates the successful processing of requests. Some of the frequently used status codes in this class are as follows:

200 OK: This code indicates that the request is successful, and the response content is returned to the client as appropriate.
201 Created: This code indicates that the request is successful and a new resource is created.
204 No Content: This code indicates that the request was processed successfully, but there is no return value for it. You may find such status codes in response to the deletion of a resource.

3xx Redirection

This series of status codes indicates that the client needs to perform further actions to logically end the request. A frequently used status code in this class is as follows:

304 Not Modified: This status indicates that the resource has not been modified since it was last accessed. This code is returned only when allowed by the client via setting the request headers as If-Modified-Since or If-None-Match. The client can take appropriate action on the basis of this status code.

4xx Client Error

This series of status codes indicates an error in processing the request. Some of the frequently used status codes in this class are as follows:

400 Bad Request: This code indicates that the server failed to process the request because of the malformed syntax in the request. The client can try again after correcting the request.
401 Unauthorized: This code indicates that authentication is required for the resource. The client can try again with appropriate authentication.
403 Forbidden: This code indicates that the server is refusing to respond to the request even if it is valid. If the request is not a HEAD method, the reason will be listed in the body content.
404 Not Found: This code indicates that the requested resource is not found at the location specified in the request.
405 Method Not Allowed: This code indicates that the HTTP method specified in the request is not allowed on the resource identified by the URI.
408 Request Timeout: This code indicates that the client failed to respond within the time window set on the server.
409 Conflict: This code indicates that the request cannot be completed because it conflicts with some rules established on resources, such as validation failure.

5xx Server Error

This series of status codes indicates server failures while processing a valid request. Here are some of the frequently used status codes in this class:

500 Internal Server Error: This code indicates a generic error message, and it tells that an unexpected error occurred on the server and that the request cannot be fulfilled.
501 Not Implemented: The server either does not recognize the request method or cannot fulfil the request. Usually, this implies future availability (e.g., a new feature of a web-service API).
502 Bad Gateway: This code indicates that the server received an invalid response from an inbound server.
503 Service Unavailable: This code indicates that the server is currently unable to handle the request due to temporary overload or scheduled maintenance.
504 Gateway Timeout: This code indicates that the server, acting as a gateway, did not receive a timely response from the upstream server.

Summary of HTTP Status Codes

1xx Informational

100 Continue
101 Switching Protocols
102 Processing

2xx Success

200 OK
201 Created
202 Accepted
203 Non-authoritative Information
204 No Content
205 Reset Content
206 Partial Content
207 Multi-Status
208 Already Reported
226 IM Used

3xx Redirection

300 Multiple Choices
301 Moved Permanently
302 Found
303 See Other
304 Not Modified
305 Use Proxy
307 Temporary Redirect
308 Permanent Redirect

4xx Client Error

400 Bad Request
401 Unauthorized
402 Payment Required
403 Forbidden
404 Not Found
405 Method Not Allowed
406 Not Acceptable
407 Proxy Authentication Required
408 Request Timeout
409 Conflict
410 Gone
411 Length Required
412 Precondition Failed
413 Payload Too Large
414 Request-URI Too Long
415 Unsupported Media Type
416 Requested Range Not Satisfiable
417 Expectation Failed
418 I’m a teapot
421 Misdirected Request
422 Unprocessable Entity
423 Locked
424 Failed Dependency
426 Upgrade Required
428 Precondition Required
429 Too Many Requests
431 Request Header Fields Too Large
444 Connection Closed Without Response
451 Unavailable For Legal Reasons
499 Client Closed Request

5xx Server Error

500 Internal Server Error
501 Not Implemented
502 Bad Gateway
503 Service Unavailable
504 Gateway Timeout
505 HTTP Version Not Supported
506 Variant Also Negotiates
507 Insufficient Storage
508 Loop Detected
510 Not Extended
511 Network Authentication Required
599 Network Connect Timeout Error

You can check out all the HTTP status codes on the Mozilla Developer Network.

Using HTTP Status Codes

REST APIs for user management applications often involve several status codes for different operations. Here are some examples of REST APIs for user resources and their status codes:

API List

Conclusion

In this article, we have learned about commonly used HTTP status codes.

Learn how to develop REST APIs using the Jersey framework at JavaGuides.

Learn how to develop REST APIs using JAX-RS with the RESTEasy framework at JavaGuides.

Java Guides

Search This Blog