300 Multiple Choices
Description
The 300 Multiple Choices status code indicates that the requested resource has multiple representations, each with different characteristics, and the user (or user agent) should choose one of them. This status code is used when the server cannot or will not make the choice itself.
This status code is typically used when a resource is available in different formats, languages, or versions, and the server wants to let the client decide which one to use. The choices might be listed in the response payload, or they might be provided via the Link header field.
The 300 Multiple Choices status can be used in content negotiation scenarios where the server cannot determine the best representation based on the client's request headers (such as Accept, Accept-Language, etc.).
Syntax
The server responds with a 300 Multiple Choices status and typically includes information about the available choices:
HTTP/1.1 300 Multiple Choices
Content-Type: text/html
Content-Length: [length in bytes]
Location: [preferred choice URI, optional]
[Response body describing the available choices]
Examples
Multiple Format Example
A client requests a resource that's available in multiple formats:
Client Request:
Server Response:
HTTP/1.1 300 Multiple Choices
Content-Type: text/html
Content-Length: 543
<!DOCTYPE html>
<html>
<head>
<title>Multiple Choices Available</title>
</head>
<body>
<h1>Document Available in Multiple Formats</h1>
<ul>
<li><a href="/document.html">HTML Version</a></li>
<li><a href="/document.pdf">PDF Version</a></li>
<li><a href="/document.docx">Microsoft Word Version</a></li>
<li><a href="/document.txt">Plain Text Version</a></li>
</ul>
</body>
</html>
Multiple Language Example
A client requests a resource that's available in multiple languages:
Client Request:
Server Response:
HTTP/1.1 300 Multiple Choices
Content-Type: application/json
Content-Length: 287
{
"available_languages": [
{
"language": "English",
"locale": "en-US",
"url": "/about?lang=en-US"
},
{
"language": "Français",
"locale": "fr-FR",
"url": "/about?lang=fr-FR"
},
{
"language": "Español",
"locale": "es-ES",
"url": "/about?lang=es-ES"
},
{
"language": "Deutsch",
"locale": "de-DE",
"url": "/about?lang=de-DE"
}
]
}
Multiple Version Example with Link Headers
A client requests an API resource that has multiple versions:
Client Request:
Server Response:
HTTP/1.1 300 Multiple Choices
Content-Type: text/plain
Content-Length: 158
Link: </api/v1/users>; rel="alternate"; title="API Version 1"
Link: </api/v2/users>; rel="alternate"; title="API Version 2"
Link: </api/v3/users>; rel="alternate"; title="API Version 3 (Latest)"
Multiple API versions are available for this resource.
Please select one of the available versions by following the appropriate link in the Link headers.
Version 3 is recommended for new integrations.
Summary
The 300 Multiple Choices status code provides a mechanism for servers to inform clients about multiple available representations of a resource. This enables content negotiation and allows clients to select the most appropriate version based on their capabilities or preferences. While not as commonly used as other 3xx redirection status codes, it offers a standardized way to handle scenarios where multiple valid options exist for a single resource URI. The server may suggest a preferred choice using the Location header, but ultimately leaves the decision to the client.