300 Multiple Choices
HTTP response status code 300 Multiple Choices is returned by the server to indicate that more than one HTTP response is available as a result of the HTTP request. It is the client’s responsibility to select which of the presented options best fits their requirements.
The HTTP response is cacheable by default. If the default behavior needs to be overridden then the HTTP response must include the appropriate HTTP caching headers.
Usage
When the 300 Multiple Choices status code is received, the contents of the message body may differ, depending on the HTTP request. In the case of an HTTP HEAD request, no message body is included. For other HTTP requests, the message body will contain a list from which the client can choose the most appropriate response.
Each resource choice can be specified using the URI, Alternates, or Link HTTP headers. However, specification RFC 7231 recommends the Link HTTP header and points out that URI and Alternates have been deprecated. If there is a default HTTP response, or the server has a preferred choice, then it can specify this in a Location HTTP header.
Example
In the example, the client requests a resource and the server has multiple available options. The HTTP headers include paths to each of the resource options. If this were a HTTP HEAD request, the client presents a way to choose which Link to follow, but may automatically select that specified by the Location HTTP header.
Since this HTTP response follows a HTTP GET request, a message body is included to present the client with a clickable list of options.
Request
GET /tech-news HTTP/1.1
Host: www.example.re
Response
HTTP/1.1 300 Multiple Choices
Link: </leading/news.html>; rel="alternate"
Link: </bleeding/news.html>; rel="alternate"
Location: </leading/news.html>
Content-Type: text/html
Content-Length: 164
<h2>Choose from one of the following</h2>
<ul>
<li><a href=/leading/news.html>Leading edge news</a>
<li><a href=/bleeding/news.html>Bleeding edge news</a>
</ul>
Code references
.NET
HttpStatusCode.MultipleChoices
Rust
http::StatusCode::MULTIPLE_CHOICES
Rails
:multiple_choices
Go
http.StatusMultipleChoices
Symfony
Response::HTTP_MULTIPLE_CHOICES
Python3.5+
http.HTTPStatus.MULTIPLE_CHOICES
Java
java.net.HttpURLConnection.HTTP_MULT_CHOICE
Apache HttpComponents Core
org.apache.hc.core5.http.HttpStatus.SC_MULTIPLE_CHOICES
Angular
@angular/common/http/HttpStatusCode.MultipleChoices
Takeaway
The 300 Multiple Choices status code indicates that the HTTP request was successful but only in that it returns multiple resource options. The server expects the client to engage in reactive negotiation by selecting the link that best fits their requirement, although a default or server-suggested choice can be specified.