REST API - HTTP Status Codes

Author:
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.

Comments

Post a Comment

Leave Comment