HTTP Status Codes
From: https://www.rfc-editor.org/rfc/rfc9110.html#status.codes
15. Status Codes
The status code of a response is a three-digit integer code that describes
the result of the request and the semantics of the response, including
whether the request was successful and what content is enclosed (if any).
All valid status codes are within the range of 100 to 599, inclusive.
The first digit of the status code defines the class of response. The last
two digits do not have any categorization role. There are five values for
the first digit:
- 1xx (Informational): The request was received, continuing process
- 2xx (Successful): The request was successfully received, understood, and
accepted
- 3xx (Redirection): Further action needs to be taken in order to
complete the request
- 4xx (Client Error): The request contains bad syntax or
cannot be fulfilled
- 5xx (Server Error): The server failed to fulfill an
apparently valid request
HTTP status codes are extensible. A client is not
required to understand the meaning of all registered status codes, though
such understanding is obviously desirable. However, a client MUST understand
the class of any status code, as indicated by the first digit, and treat an
unrecognized status code as being equivalent to the x00 status code of that
class. For example, if a client receives an unrecognized status code of 471,
it can see from the first digit that there was something wrong with its
request and treat the response as if it had received a 400 (Bad Request)
status code. The response message will usually contain a representation that
explains the status. Values outside the range 100..599 are invalid.
Implementations often use three-digit integer values outside of that range
(i.e., 600..999) for internal communication of non-HTTP status (e.g.,
library errors). A client that receives a response with an invalid status
code SHOULD process the response as if it had a 5xx (Server Error) status
code.
A single request can have multiple associated responses: zero or more
"interim" (non-final) responses with status codes in the "informational"
(1xx) range, followed by exactly one "final" response with a status code in
one of the other ranges.
15.1. Overview of Status Codes
The status codes listed below are defined in this specification. The reason
phrases listed here are only recommendations -- they can be replaced by
local equivalents or left out altogether without affecting the protocol.
Responses with status codes that are defined as heuristically cacheable
(e.g., 200, 203, 204, 206, 300, 301, 308, 404, 405, 410, 414, and 501 in
this specification) can be reused by a cache with heuristic expiration
unless otherwise indicated by the method definition or explicit cache
controls [CACHING]; all other status codes are not heuristically cacheable.
Additional status codes, outside the scope of this specification, have been
specified for use in HTTP. All such status codes ought to be registered
within the "Hypertext Transfer Protocol (HTTP) Status Code Registry", as
described in Section 16.2.
15.2. Informational 1xx
The 1xx (Informational) class of status code indicates an interim response
for communicating connection status or request progress prior to completing
the requested action and sending a final response. Since HTTP/1.0 did not
define any 1xx status codes, a server MUST NOT send a 1xx response to an
HTTP/1.0 client.
A 1xx response is terminated by the end of the header section; it cannot
contain content or trailers. A client MUST be able to parse one or more 1xx
responses received prior to a final response, even if the client does not
expect one. A user agent MAY ignore unexpected 1xx responses. A proxy MUST
forward 1xx responses unless the proxy itself requested the generation of
the 1xx response. For example, if a proxy adds an "Expect: 100-continue"
header field when it forwards a request, then it need not forward the
corresponding 100 (Continue) response(s).
15.2.1. 100 Continue
The 100 (Continue) status code indicates that the initial part of a request
has been received and has not yet been rejected by the server. The server
intends to send a final response after the request has been fully received
and acted upon.
When the request contains an Expect header field that includes a 100
-continue expectation, the 100 response indicates that the server wishes to
receive the request content, as described in Section 10.1.1. The client
ought to continue sending the request and discard the 100 response. If the
request did not contain an Expect header field containing the 100-continue
expectation, the client can simply discard this interim response.
15.2.2. 101 Switching Protocols
The 101 (Switching Protocols) status code indicates that the server
understands and is willing to comply with the client's request, via the
Upgrade header field (Section 7.8), for a change in the application protocol
being used on this connection. The server MUST generate an Upgrade header
field in the response that indicates which protocol(s) will be in effect
after this response.
It is assumed that the server will only agree to switch protocols when it is
advantageous to do so. For example, switching to a newer version of HTTP
might be advantageous over older versions, and switching to a real-time,
synchronous protocol might be advantageous when delivering resources that
use such features.
15.3. Successful 2xx
The 2xx (Successful) class of status code indicates that the client's
request was successfully received, understood, and accepted.
15.3.1. 200 OK
The 200 (OK) status code indicates that the request has succeeded. The
content sent in a 200 response depends on the request method. For the
methods defined by this specification, the intended meaning of the content
can be summarized as:
Table 6
| Request Method | Response content is a representation of:
|
| GET | the target resource
|
| HEAD | the target resource, like GET, but without transferring the
|
| representation data
|
| POST | the status of, or results obtained from, the action
|
| PUT, DELETE | the status of the action
|
| OPTIONS | communication options for the target resource
|
| TRACE | the request message as received by the server returning the trace
|
Aside from responses to CONNECT, a 200 response is expected to contain
message content unless the message framing explicitly indicates that the
content has zero length. If some aspect of the request indicates a
preference for no content upon success, the origin server ought to send a
204 (No Content) response instead. For CONNECT, there is no content because
the successful result is a tunnel, which begins immediately after the 200
response header section.
A 200 response is heuristically cacheable; i.e., unless otherwise indicated
by the method definition or explicit cache controls (see Section 4.2.2 of
[CACHING]). In 200 responses to GET or HEAD, an origin server SHOULD send
any available validator fields (Section 8.8) for the selected
representation, with both a strong entity tag and a Last-Modified date being
preferred. In 200 responses to state-changing methods, any validator fields
(Section 8.8) sent in the response convey the current validators for the new
representation formed as a result of successfully applying the request
semantics. Note that the PUT method (Section 9.3.4) has additional
requirements that might preclude sending such validators.
15.3.2. 201 Created
The 201 (Created) status code indicates that the request has been fulfilled
and has resulted in one or more new resources being created. The primary
resource created by the request is identified by either a Location header
field in the response or, if no Location header field is received, by the
target URI.
The 201 response content typically describes and links to the resource(s)
created. Any validator fields (Section 8.8) sent in the response convey the
current validators for a new representation created by the request. Note
that the PUT method (Section 9.3.4) has additional requirements that might
preclude sending such validators.
15.3.3. 202 Accepted
The 202 (Accepted) status code indicates that the request has been accepted
for processing, but the processing has not been completed. The request might
or might not eventually be acted upon, as it might be disallowed when
processing actually takes place. There is no facility in HTTP for re-sending
a status code from an asynchronous operation.
The 202 response is intentionally noncommittal. Its purpose is to allow a
server to accept a request for some other process (perhaps a batch-oriented
process that is only run once per day) without requiring that the user
agent's connection to the server persist until the process is completed. The
representation sent with this response ought to describe the request's
current status and point to (or embed) a status monitor that can provide the
user with an estimate of when the request will be fulfilled.
15.3.4. 203 Non-Authoritative Information
The 203 (Non-Authoritative Information) status code indicates that the
request was successful but the enclosed content has been modified from that
of the origin server's 200 (OK) response by a transforming proxy (Section
7.7). This status code allows the proxy to notify recipients when a
transformation has been applied, since that knowledge might impact later
decisions regarding the content. For example, future cache validation
requests for the content might only be applicable along the same request
path (through the same proxies).
A 203 response is heuristically cacheable; i.e., unless otherwise indicated
by the method definition or explicit cache controls (see Section 4.2.2 of
[CACHING]).
15.3.5. 204 No Content
The 204 (No Content) status code indicates that the server has successfully
fulfilled the request and that there is no additional content to send in the
response content. Metadata in the response header fields refer to the target
resource and its selected representation after the requested action was
applied.
For example, if a 204 status code is received in response to a PUT request
and the response contains an ETag field, then the PUT was successful and the
ETag field value contains the entity tag for the new representation of that
target resource. The 204 response allows a server to indicate that the
action has been successfully applied to the target resource, while implying
that the user agent does not need to traverse away from its current
"document view" (if any). The server assumes that the user agent will
provide some indication of the success to its user, in accord with its own
interface, and apply any new or updated metadata in the response to its
active representation. For example, a 204 status code is commonly used with
document editing interfaces corresponding to a "save" action, such that the
document being saved remains available to the user for editing. It is also
frequently used with interfaces that expect automated data transfers to be
prevalent, such as within distributed version control systems. A 204
response is terminated by the end of the header section; it cannot contain
content or trailers. A 204 response is heuristically cacheable; i.e., unless
otherwise indicated by the method definition or explicit cache controls (see
Section 4.2.2 of [CACHING]).
15.3.6. 205 Reset Content
The 205 (Reset Content) status code indicates that the server has fulfilled
the request and desires that the user agent reset the "document view", which
caused the request to be sent, to its original state as received from the
origin server.
This response is intended to support a common data entry use case where the
user receives content that supports data entry (a form, notepad, canvas,
etc.), enters or manipulates data in that space, causes the entered data to
be submitted in a request, and then the data entry mechanism is reset for
the next entry so that the user can easily initiate another input action.
Since the 205 status code implies that no additional content will be
provided, a server MUST NOT generate content in a 205 response.
15.3.7. 206 Partial Content
The 206 (Partial Content) status code indicates that the server is
successfully fulfilling a range request for the target resource by
transferring one or more parts of the selected representation.
A server that supports range requests (Section 14) will usually attempt to
satisfy all of the requested ranges, since sending less data will likely
result in another client request for the remainder. However, a server might
want to send only a subset of the data requested for reasons of its own,
such as temporary unavailability, cache efficiency, load balancing, etc.
Since a 206 response is self-descriptive, the client can still understand a
response that only partially satisfies its range request. A client MUST
inspect a 206 response's Content-Type and Content-Range field(s) to
determine what parts are enclosed and whether additional requests are
needed. A server that generates a 206 response MUST generate the following
header fields, in addition to those required in the subsections below, if
the field would have been sent in a 200 (OK) response to the same request:
Date, Cache-Control, ETag, Expires, Content-Location, and Vary. A Content
-Length header field present in a 206 response indicates the number of
octets in the content of this message, which is usually not the complete
length of the selected representation. Each Content-Range header field
includes information about the selected representation's complete length. A
sender that generates a 206 response to a request with an If-Range header
field SHOULD NOT generate other representation header fields beyond those
required because the client already has a prior response containing those
header fields. Otherwise, a sender MUST generate all of the representation
header fields that would have been sent in a 200 (OK) response to the same
request. A 206 response is heuristically cacheable; i.e., unless otherwise
indicated by explicit cache controls (see Section 4.2.2 of [CACHING]).
15.3.7.1. Single Part
If a single part is being transferred, the server generating the 206
response MUST generate a Content-Range header field, describing what range
of the selected representation is enclosed, and a content consisting of the
range. For example:
HTTP/1.1 206 Partial Content
Date: Wed, 15 Nov 1995 06:25:24 GMT
Last-Modified: Wed, 15 Nov 1995 04:58:08 GMT
Content-Range: bytes 21010-47021/47022
Content-Length: 26012
Content-Type: image/gif
... 26012 bytes of partial image data ...
15.3.7.2. Multiple Parts
If multiple parts are being transferred, the server generating the 206
response MUST generate "multipart/byteranges" content, as defined in Section
14.6, and a Content-Type header field containing the "multipart/byteranges"
media type and its required boundary parameter. To avoid confusion with
single-part responses, a server MUST NOT generate a Content-Range header
field in the HTTP header section of a multiple part response (this field
will be sent in each part instead).
Within the header area of each body part in the multipart content, the
server MUST generate a Content-Range header field corresponding to the range
being enclosed in that body part. If the selected representation would have
had a Content-Type header field in a 200 (OK) response, the server SHOULD
generate that same Content-Type header field in the header area of each body part.
For example:
HTTP/1.1 206 Partial Content
Date: Wed, 15 Nov 1995 06:25:24 GMT
Last-Modified: Wed, 15 Nov 1995 04:58:08 GMT
Content-Length: 1741
Content-Type: multipart/byteranges; boundary=THIS_STRING_SEPARATES
--THIS_STRING_SEPARATES
Content-Type: application/pdf
Content-Range: bytes 500-999/8000
...the first range...
--THIS_STRING_SEPARATES
Content-Type: application/pdf
Content-Range: bytes 7000-7999/8000
...the second range
--THIS_STRING_SEPARATES--
When multiple ranges are requested, a server MAY coalesce any of the ranges
that overlap, or that are separated by a gap that is smaller than the
overhead of sending multiple parts, regardless of the order in which the
corresponding range-spec appeared in the received Range header field. Since
the typical overhead between each part of a "multipart/byteranges" is around
80 bytes, depending on the selected representation's media type and the
chosen boundary parameter length, it can be less efficient to transfer many
small disjoint parts than it is to transfer the entire selected
representation. A server MUST NOT generate a multipart response to a request
for a single range, since a client that does not request multiple parts
might not support multipart responses. However, a server MAY generate a
"multipart/byteranges" response with only a single body part if multiple
ranges were requested and only one range was found to be satisfiable or only
one range remained after coalescing. A client that cannot process a
"multipart/byteranges" response MUST NOT generate a request that asks for
multiple ranges. A server that generates a multipart response SHOULD send
the parts in the same order that the corresponding range-spec appeared in
the received Range header field, excluding those ranges that were deemed
unsatisfiable or that were coalesced into other ranges. A client that
receives a multipart response MUST inspect the Content-Range header field
present in each body part in order to determine which range is contained in
that body part; a client cannot rely on receiving the same ranges that it
requested, nor the same order that it requested.
15.3.7.3. Combining Parts
A response might transfer only a subrange of a representation if the
connection closed prematurely or if the request used one or more Range
specifications. After several such transfers, a client might have received
several ranges of the same representation. These ranges can only be safely
combined if they all have in common the same strong validator (Section
8.8.1).
A client that has received multiple partial responses to GET requests on a
target resource MAY combine those responses into a larger continuous range
if they share the same strong validator. If the most recent response is an
incomplete 200 (OK) response, then the header fields of that response are
used for any combined response and replace those of the matching stored
responses. If the most recent response is a 206 (Partial Content) response
and at least one of the matching stored responses is a 200 (OK), then the
combined response header fields consist of the most recent 200 response's
header fields. If all of the matching stored responses are 206 responses,
then the stored response with the most recent header fields is used as the
source of header fields for the combined response, except that the client
MUST use other header fields provided in the new response, aside from
Content-Range, to replace all instances of the corresponding header fields
in the stored response. The combined response content consists of the union
of partial content ranges within the new response and all of the matching
stored responses. If the union consists of the entire range of the
representation, then the client MUST process the combined response as if it
were a complete 200 (OK) response, including a Content-Length header field
that reflects the complete length. Otherwise, the client MUST process the
set of continuous ranges as one of the following: an incomplete 200 (OK)
response if the combined response is a prefix of the representation, a
single 206 (Partial Content) response containing "multipart/byteranges"
content, or multiple 206 (Partial Content) responses, each with one
continuous range that is indicated by a Content-Range header field.
15.4 Redirection 3xx
The 3xx (Redirection) class of status code indicates that further action
needs to be taken by the user agent in order to fulfill the request. There
are several types of redirects:
Redirects that indicate this resource might be available at a different URI,
as provided by the Location header field, as in the status codes 301 (Moved
Permanently), 302 (Found), 307 (Temporary Redirect), and 308 (Permanent
Redirect).
Redirection that offers a choice among matching resources capable of
representing this resource, as in the 300 (Multiple Choices) status code.
Redirection to a different resource, identified by the Location header
field, that can represent an indirect response to the request, as in the 303
(See Other) status code. Redirection to a previously stored result, as in
the 304 (Not Modified) status code.
Note:
In HTTP/1.0, the status codes 301 (Moved Permanently) and 302 (Found)
were originally defined as method-preserving ([HTTP/1.0], Section 9.3) to
match their implementation at CERN; 303 (See Other) was defined for a
redirection that changed its method to GET. However, early user agents split
on whether to redirect POST requests as POST (according to then-current
specification) or as GET (the safer alternative when redirected to a
different site). Prevailing practice eventually converged on changing the
method to GET. 307 (Temporary Redirect) and 308 (Permanent Redirect)
[RFC7538] were later added to unambiguously indicate method-preserving
redirects, and status codes 301 and 302 have been adjusted to allow a POST
request to be redirected as GET.
If a Location header field (Section 10.2.2) is provided, the user agent MAY
automatically redirect its request to the URI referenced by the Location
field value, even if the specific status code is not understood. Automatic
redirection needs to be done with care for methods not known to be safe, as
defined in Section 9.2.1, since the user might not wish to redirect an
unsafe request. When automatically following a redirected request, the user
agent SHOULD resend the original request message with the following
modifications:
- Replace the target URI with the URI referenced by the redirection response's
Location header field value after resolving it relative to the original
request's target URI.
- Remove header fields that were automatically generated by the
implementation, replacing them with updated values as appropriate to the new
request. This includes:
- Connection-specific header fields (see Section 7.6.1),
- Header fields specific to the client's proxy configuration, including
(but not limited to) Proxy-Authorization,
- Origin-specific header fields (if any), including (but not limited to)
Host,
- Validating header fields that were added by the implementation's cache
(e.g., If-None-Match, If-Modified-Since), and
- Resource-specific header fields, including (but not limited to) Referer,
Origin, Authorization, and Cookie.
- Consider removing header fields that were not automatically generated by the
implementation (i.e., those present in the request because they were added
by the calling context) where there are security implications; this includes
but is not limited to Authorization and Cookie.
- Change the request method according to the redirecting status code's
semantics, if applicable.
- If the request method has been changed to GET or HEAD, remove content
-specific header fields, including (but not limited to) Content-Encoding,
Content-Language, Content-Location, Content-Type, Content-Length, Digest,
Last-Modified.
A client SHOULD detect and intervene in cyclical redirections (i.e.,
"infinite" redirection loops).
Note:
An earlier version of this specification recommended a maximum of five
redirections ([RFC2068], Section 10.3). Content developers need to be aware
that some clients might implement such a fixed limitation.
15.4.1. 300 Multiple Choices
The 300 (Multiple Choices) status code indicates that the target resource
has more than one representation, each with its own more specific
identifier, and information about the alternatives is being provided so that
the user (or user agent) can select a preferred representation by
redirecting its request to one or more of those identifiers. In other words,
the server desires that the user agent engage in reactive negotiation to
select the most appropriate representation(s) for its needs (Section 12).
If the server has a preferred choice, the server SHOULD generate a Location
header field containing a preferred choice's URI reference. The user agent
MAY use the Location field value for automatic redirection. For request
methods other than HEAD, the server SHOULD generate content in the 300
response containing a list of representation metadata and URI reference(s)
from which the user or user agent can choose the one most preferred. The
user agent MAY make a selection from that list automatically if it
understands the provided media type. A specific format for automatic
selection is not defined by this specification because HTTP tries to remain
orthogonal to the definition of its content. In practice, the representation
is provided in some easily parsed format believed to be acceptable to the
user agent, as determined by shared design or content negotiation, or in
some commonly accepted hypertext format. A 300 response is heuristically
cacheable; i.e., unless otherwise indicated by the method definition or
explicit cache controls (see Section 4.2.2 of [CACHING]).
Note:
The original proposal for the 300 status code defined the URI header
field as providing a list of alternative representations, such that it would
be usable for 200, 300, and 406 responses and be transferred in responses to
the HEAD method. However, lack of deployment and disagreement over syntax
led to both URI and Alternates (a subsequent proposal) being dropped from
this specification. It is possible to communicate the list as a Link header
field value [RFC8288] whose members have a relationship of "alternate",
though deployment is a chicken-and-egg problem.
15.4.2. 301 Moved Permanently
The 301 (Moved Permanently) status code indicates that the target resource
has been assigned a new permanent URI and any future references to this
resource ought to use one of the enclosed URIs. The server is suggesting
that a user agent with link-editing capability can permanently replace
references to the target URI with one of the new references sent by the
server. However, this suggestion is usually ignored unless the user agent is
actively editing references (e.g., engaged in authoring content), the
connection is secured, and the origin server is a trusted authority for the
content being edited.
The server SHOULD generate a Location header field in the response
containing a preferred URI reference for the new permanent URI. The user
agent MAY use the Location field value for automatic redirection. The
server's response content usually contains a short hypertext note with a
hyperlink to the new URI(s).
Note:
For historical reasons, a user agent MAY change the request method
from POST to GET for the subsequent request. If this behavior is undesired,
the 308 (Permanent Redirect) status code can be used instead.
A 301 response is heuristically cacheable; i.e., unless otherwise indicated
by the method definition or explicit cache controls (see Section 4.2.2 of
[CACHING]).
15.4.3. 302 Found
The 302 (Found) status code indicates that the target resource resides
temporarily under a different URI. Since the redirection might be altered on
occasion, the client ought to continue to use the target URI for future
requests.
The server SHOULD generate a Location header field in the response
containing a URI reference for the different URI. The user agent MAY use the
Location field value for automatic redirection. The server's response
content usually contains a short hypertext note with a hyperlink to the
different URI(s).
Note:
For historical reasons, a user agent MAY change the request method
from POST to GET for the subsequent request. If this behavior is undesired,
the 307 (Temporary Redirect) status code can be used instead.
15.4.4. 303 See Other
The 303 (See Other) status code indicates that the server is redirecting the
user agent to a different resource, as indicated by a URI in the Location
header field, which is intended to provide an indirect response to the
original request. A user agent can perform a retrieval request targeting
that URI (a GET or HEAD request if using HTTP), which might also be
redirected, and present the eventual result as an answer to the original
request. Note that the new URI in the Location header field is not
considered equivalent to the target URI.
This status code is applicable to any HTTP method. It is primarily used to
allow the output of a POST action to redirect the user agent to a different
resource, since doing so provides the information corresponding to the POST
response as a resource that can be separately identified, bookmarked, and
cached. A 303 response to a GET request indicates that the origin server
does not have a representation of the target resource that can be
transferred by the server over HTTP. However, the Location field value
refers to a resource that is descriptive of the target resource, such that
making a retrieval request on that other resource might result in a
representation that is useful to recipients without implying that it
represents the original target resource. Note that answers to the questions
of what can be represented, what representations are adequate, and what
might be a useful description are outside the scope of HTTP. Except for
responses to a HEAD request, the representation of a 303 response ought to
contain a short hypertext note with a hyperlink to the same URI reference
provided in the Location header field.
15.4.5. 304 Not Modified
The 304 (Not Modified) status code indicates that a conditional GET or HEAD
request has been received and would have resulted in a 200 (OK) response if
it were not for the fact that the condition evaluated to false. In other
words, there is no need for the server to transfer a representation of the
target resource because the request indicates that the client, which made
the request conditional, already has a valid representation; the server is
therefore redirecting the client to make use of that stored representation
as if it were the content of a 200 (OK) response.
The server generating a 304 response MUST generate any of the following
header fields that would have been sent in a 200 (OK) response to the same
request:
- Content-Location, Date, ETag, and Vary
- Cache-Control and Expires (see [CACHING])
Since the goal of a 304 response is to minimize information transfer when the
recipient already has one or more cached representations, a sender SHOULD NOT
generate representation metadata other than the above listed fields unless said
metadata exists for the purpose of guiding cache updates (e.g., Last-Modified
might be useful if the response does not have an ETag field). Requirements on a
cache that receives a 304 response are defined in Section 4.3.4 of [CACHING].
If the conditional request originated with an outbound client, such as a user
agent with its own cache sending a conditional GET to a shared proxy, then the
proxy SHOULD forward the 304 response to that client. A 304 response is
terminated by the end of the header section; it cannot contain content or
trailers.
15.4.6. 305 Use Proxy
The 305 (Use Proxy) status code was defined in a previous version of this
specification and is now deprecated (Appendix B of [RFC7231]).
15.4.7. 306 (Unused)
The 306 status code was defined in a previous version of this specification,
is no longer used, and the code is reserved.
15.4.8. 307 Temporary Redirect
The 307 (Temporary Redirect) status code indicates that the target resource
resides temporarily under a different URI and the user agent MUST NOT change
the request method if it performs an automatic redirection to that URI.
Since the redirection can change over time, the client ought to continue
using the original target URI for future requests.
The server SHOULD generate a Location header field in the response
containing a URI reference for the different URI. The user agent MAY use the
Location field value for automatic redirection. The server's response
content usually contains a short hypertext note with a hyperlink to the
different URI(s).
15.4.9. 308 Permanent Redirect
The 308 (Permanent Redirect) status code indicates that the target resource
has been assigned a new permanent URI and any future references to this
resource ought to use one of the enclosed URIs. The server is suggesting
that a user agent with link-editing capability can permanently replace
references to the target URI with one of the new references sent by the
server. However, this suggestion is usually ignored unless the user agent is
actively editing references (e.g., engaged in authoring content), the
connection is secured, and the origin server is a trusted authority for the
content being edited.
The server SHOULD generate a Location header field in the response
containing a preferred URI reference for the new permanent URI. The user
agent MAY use the Location field value for automatic redirection. The
server's response content usually contains a short hypertext note with a
hyperlink to the new URI(s). A 308 response is heuristically cacheable;
i.e., unless otherwise indicated by the method definition or explicit cache
controls (see Section 4.2.2 of [CACHING]).
Note:
This status code is much younger (June 2014) than its sibling codes
and thus might not be recognized everywhere. See Section 4 of [RFC7538] for
deployment considerations.
15.5. Client Error 4xx
The 4xx (Client Error) class of status code indicates that the client seems
to have erred. Except when responding to a HEAD request, the server SHOULD
send a representation containing an explanation of the error situation, and
whether it is a temporary or permanent condition. These status codes are
applicable to any request method. User agents SHOULD display any included
representation to the user.
15.5.1. 400 Bad Request
The 400 (Bad Request) status code indicates that the server cannot or will
not process the request due to something that is perceived to be a client
error (e.g., malformed request syntax, invalid request message framing, or
deceptive request routing).
15.5.2. 401 Unauthorized
The 401 (Unauthorized) status code indicates that the request has not been
applied because it lacks valid authentication credentials for the target
resource. The server generating a 401 response MUST send a WWW-Authenticate
header field (Section 11.6.1) containing at least one challenge applicable
to the target resource.
If the request included authentication credentials, then the 401 response
indicates that authorization has been refused for those credentials. The
user agent MAY repeat the request with a new or replaced Authorization
header field (Section 11.6.2). If the 401 response contains the same
challenge as the prior response, and the user agent has already attempted
authentication at least once, then the user agent SHOULD present the
enclosed representation to the user, since it usually contains relevant
diagnostic information.
15.5.3. 402 Payment Required
The 402 (Payment Required) status code is reserved for future use.
15.5.4. 403 Forbidden
The 403 (Forbidden) status code indicates that the server understood the
request but refuses to fulfill it. A server that wishes to make public why
the request has been forbidden can describe that reason in the response
content (if any).
If authentication credentials were provided in the request, the server
considers them insufficient to grant access. The client SHOULD NOT
automatically repeat the request with the same credentials. The client MAY
repeat the request with new or different credentials. However, a request
might be forbidden for reasons unrelated to the credentials. An origin
server that wishes to "hide" the current existence of a forbidden target
resource MAY instead respond with a status code of 404 (Not Found).
15.5.5. 404 Not Found
The 404 (Not Found) status code indicates that the origin server did not
find a current representation for the target resource or is not willing to
disclose that one exists. A 404 status code does not indicate whether this
lack of representation is temporary or permanent; the 410 (Gone) status code
is preferred over 404 if the origin server knows, presumably through some
configurable means, that the condition is likely to be permanent.
A 404 response is heuristically cacheable; i.e., unless otherwise indicated
by the method definition or explicit cache controls (see Section 4.2.2 of
[CACHING]).
15.5.6. 405 Method Not Allowed
The 405 (Method Not Allowed) status code indicates that the method received
in the request-line is known by the origin server but not supported by the
target resource. The origin server MUST generate an Allow header field in a
405 response containing a list of the target resource's currently supported
methods.
A 405 response is heuristically cacheable; i.e., unless otherwise indicated
by the method definition or explicit cache controls (see Section 4.2.2 of
[CACHING]).
15.5.7. 406 Not Acceptable
The 406 (Not Acceptable) status code indicates that the target resource does
not have a current representation that would be acceptable to the user
agent, according to the proactive negotiation header fields received in the
request (Section 12.1), and the server is unwilling to supply a default
representation.
The server SHOULD generate content containing a list of available
representation characteristics and corresponding resource identifiers from
which the user or user agent can choose the one most appropriate. A user
agent MAY automatically select the most appropriate choice from that list.
However, this specification does not define any standard for such automatic
selection, as described in Section 15.4.1.
15.5.8. 407 Proxy Authentication Required
The 407 (Proxy Authentication Required) status code is similar to 401
(Unauthorized), but it indicates that the client needs to authenticate
itself in order to use a proxy for this request. The proxy MUST send a Proxy
-Authenticate header field (Section 11.7.1) containing a challenge
applicable to that proxy for the request. The client MAY repeat the request
with a new or replaced Proxy-Authorization header field (Section 11.7.2).
15.5.9. 408 Request Timeout
The 408 (Request Timeout) status code indicates that the server did not
receive a complete request message within the time that it was prepared to
wait.
If the client has an outstanding request in transit, it MAY repeat that
request. If the current connection is not usable (e.g., as it would be in
HTTP/1.1 because request delimitation is lost), a new connection will be
used.
15.5.10. 409 Conflict
The 409 (Conflict) status code indicates that the request could not be
completed due to a conflict with the current state of the target resource.
This code is used in situations where the user might be able to resolve the
conflict and resubmit the request. The server SHOULD generate content that
includes enough information for a user to recognize the source of the
conflict.
Conflicts are most likely to occur in response to a PUT request. For
example, if versioning were being used and the representation being PUT
included changes to a resource that conflict with those made by an earlier
(third-party) request, the origin server might use a 409 response to
indicate that it can't complete the request. In this case, the response
representation would likely contain information useful for merging the
differences based on the revision history.
15.5.11. 410 Gone
The 410 (Gone) status code indicates that access to the target resource is
no longer available at the origin server and that this condition is likely
to be permanent. If the origin server does not know, or has no facility to
determine, whether or not the condition is permanent, the status code 404
(Not Found) ought to be used instead.
The 410 response is primarily intended to assist the task of web maintenance
by notifying the recipient that the resource is intentionally unavailable
and that the server owners desire that remote links to that resource be
removed. Such an event is common for limited-time, promotional services and
for resources belonging to individuals no longer associated with the origin
server's site. It is not necessary to mark all permanently unavailable
resources as "gone" or to keep the mark for any length of time -- that is
left to the discretion of the server owner. A 410 response is heuristically
cacheable; i.e., unless otherwise indicated by the method definition or
explicit cache controls (see Section 4.2.2 of [CACHING]).
15.5.12. 411 Length Required
The 411 (Length Required) status code indicates that the server refuses to
accept the request without a defined Content-Length (Section 8.6). The
client MAY repeat the request if it adds a valid Content-Length header field
containing the length of the request content.
15.5.13. 412 Precondition Failed
The 412 (Precondition Failed) status code indicates that one or more
conditions given in the request header fields evaluated to false when tested
on the server (Section 13). This response status code allows the client to
place preconditions on the current resource state (its current
representations and metadata) and, thus, prevent the request method from
being applied if the target resource is in an unexpected state.
15.5.14. 413 Content Too Large
The 413 (Content Too Large) status code indicates that the server is
refusing to process a request because the request content is larger than the
server is willing or able to process. The server MAY terminate the request,
if the protocol version in use allows it; otherwise, the server MAY close
the connection.
If the condition is temporary, the server SHOULD generate a Retry-After
header field to indicate that it is temporary and after what time the client
MAY try again.
15.5.15. 414 URI Too Long
The 414 (URI Too Long) status code indicates that the server is refusing to
service the request because the target URI is longer than the server is
willing to interpret. This rare condition is only likely to occur when a
client has improperly converted a POST request to a GET request with long
query information, when the client has descended into an infinite loop of
redirection (e.g., a redirected URI prefix that points to a suffix of
itself) or when the server is under attack by a client attempting to exploit
potential security holes.
A 414 response is heuristically cacheable; i.e., unless otherwise indicated
by the method definition or explicit cache controls (see Section 4.2.2 of
[CACHING]).
15.5.16. 415 Unsupported Media Type
The 415 (Unsupported Media Type) status code indicates that the origin
server is refusing to service the request because the content is in a format
not supported by this method on the target resource.
The format problem might be due to the request's indicated Content-Type or
Content-Encoding, or as a result of inspecting the data directly. If the
problem was caused by an unsupported content coding, the Accept-Encoding
response header field (Section 12.5.3) ought to be used to indicate which
(if any) content codings would have been accepted in the request. On the
other hand, if the cause was an unsupported media type, the Accept response
header field (Section 12.5.1) can be used to indicate which media types
would have been accepted in the request.
15.5.17. 416 Range Not Satisfiable
The 416 (Range Not Satisfiable) status code indicates that the set of ranges
in the request's Range header field (Section 14.2) has been rejected either
because none of the requested ranges are satisfiable or because the client
has requested an excessive number of small or overlapping ranges (a
potential denial of service attack).
Each range unit defines what is required for its own range sets to be
satisfiable. For example, Section 14.1.2 defines what makes a bytes range
set satisfiable. A server that generates a 416 response to a byte-range
request SHOULD generate a Content-Range header field specifying the current
length of the selected representation (Section 14.4). For example:
HTTP/1.1 416 Range Not Satisfiable
Date: Fri, 20 Jan 2012 15:41:54 GMT
Content-Range: bytes */47022
Note: Because servers are free to ignore Range, many implementations will
respond with the entire selected representation in a 200 (OK) response. That
is partly because most clients are prepared to receive a 200 (OK) to
complete the task (albeit less efficiently) and partly because clients might
not stop making an invalid range request until they have received a complete
representation. Thus, clients cannot depend on receiving a 416 (Range Not
Satisfiable) response even when it is most appropriate.
15.5.18. 417 Expectation Failed
The 417 (Expectation Failed) status code indicates that the expectation
given in the request's Expect header field (Section 10.1.1) could not be met
by at least one of the inbound servers.
15.5.19. 418 (Unused)
[RFC2324] was an April 1 RFC that lampooned the various ways HTTP was
abused; one such abuse was the definition of an application-specific 418
status code, which has been deployed as a joke often enough for the code to
be unusable for any future use.
Therefore, the 418 status code is reserved in the IANA HTTP Status Code
Registry. This indicates that the status code cannot be assigned to other
applications currently. If future circumstances require its use (e.g.,
exhaustion of 4NN status codes), it can be re-assigned to another use.
15.5.20. 421 Misdirected Request
The 421 (Misdirected Request) status code indicates that the request was
directed at a server that is unable or unwilling to produce an authoritative
response for the target URI. An origin server (or gateway acting on behalf
of the origin server) sends 421 to reject a target URI that does not match
an origin for which the server has been configured (Section 4.3.1) or does
not match the connection context over which the request was received
(Section 7.4).
A client that receives a 421 (Misdirected Request) response MAY retry the
request, whether or not the request method is idempotent, over a different
connection, such as a fresh connection specific to the target resource's
origin, or via an alternative service [ALTSVC]. A proxy MUST NOT generate a
421 response.
15.5.21. 422 Unprocessable Content
The 422 (Unprocessable Content) status code indicates that the server
understands the content type of the request content (hence a 415
(Unsupported Media Type) status code is inappropriate), and the syntax of
the request content is correct, but it was unable to process the contained
instructions. For example, this status code can be sent if an XML request
content contains well-formed (i.e., syntactically correct), but semantically
erroneous XML instructions.
15.5.22. 426 Upgrade Required
The 426 (Upgrade Required) status code indicates that the server refuses to
perform the request using the current protocol but might be willing to do so
after the client upgrades to a different protocol. The server MUST send an
Upgrade header field in a 426 response to indicate the required protocol(s)
(Section 7.8).
Example:
HTTP/1.1 426 Upgrade Required
Upgrade: HTTP/3.0
Connection: Upgrade
Content-Length: 53
Content-Type: text/plain
This service requires use of the HTTP/3.0 protocol.
15.6. Server Error 5xx
The 5xx (Server Error) class of status code indicates that the server is
aware that it has erred or is incapable of performing the requested method.
Except when responding to a HEAD request, the server SHOULD send a
representation containing an explanation of the error situation, and whether
it is a temporary or permanent condition. A user agent SHOULD display any
included representation to the user. These status codes are applicable to
any request method.
15.6.1. 500 Internal Server Error
The 500 (Internal Server Error) status code indicates that the server
encountered an unexpected condition that prevented it from fulfilling the
request.
15.6.2. 501 Not Implemented
The 501 (Not Implemented) status code indicates that the server does not
support the functionality required to fulfill the request. This is the
appropriate response when the server does not recognize the request method
and is not capable of supporting it for any resource.
A 501 response is heuristically cacheable; i.e., unless otherwise indicated
by the method definition or explicit cache controls (see Section 4.2.2 of
[CACHING]).
15.6.3. 502 Bad Gateway
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.
15.6.4. 503 Service Unavailable
The 503 (Service Unavailable) status code 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 (Section 10.2.3) to suggest an
appropriate amount of time for the client to wait before retrying the
request.
Note: The existence of the 503 status code does not imply that a server has
to use it when becoming overloaded. Some servers might simply refuse the
connection.
15.6.5. 504 Gateway Timeout
The 504 (Gateway Timeout) status code indicates that the server, while
acting as a gateway or proxy, did not receive a timely response from an
upstream server it needed to access in order to complete the request.
15.6.6. 505 HTTP Version Not Supported
The 505 (HTTP Version Not Supported) status code indicates that the server
does not support, or refuses to support, the major version of HTTP that was
used in the request message. The server is indicating that it is unable or
unwilling to complete the request using the same major version as the
client, as described in Section 2.5, other than with this error message. The
server SHOULD generate a representation for the 505 response that describes
why that version is not supported and what other protocols are supported by
that server.
16. Extending HTTP
HTTP defines a number of generic extension points that can be used to
introduce capabilities to the protocol without introducing a new version,
including methods, status codes, field names, and further extensibility
points within defined fields, such as authentication schemes and cache
directives (see Cache-Control extensions in Section 5.2.3 of [CACHING]).
Because the semantics of HTTP are not versioned, these extension points are
persistent; the version of the protocol in use does not affect their
semantics.
Version-independent extensions are discouraged from depending on or
interacting with the specific version of the protocol in use. When this is
unavoidable, careful consideration needs to be given to how the extension
can interoperate across versions. Additionally, specific versions of HTTP
might have their own extensibility points, such as transfer codings in
HTTP/1.1 (Section 6.1 of [HTTP/1.1]) and HTTP/2 SETTINGS or frame types
([HTTP/2]). These extension points are specific to the version of the
protocol they occur within. Version-specific extensions cannot override or
modify the semantics of a version-independent mechanism or extension point
(like a method or header field) without explicitly being allowed by that
protocol element. For example, the CONNECT method (Section 9.3.6) allows
this. These guidelines assure that the protocol operates correctly and
predictably, even when parts of the path implement different versions of
HTTP.
16.1. Method Extensibility
16.1.1. Method Registry
The "Hypertext Transfer Protocol (HTTP) Method Registry", maintained by IANA
at , registers method names.
HTTP method registrations MUST include the following fields:
Method Name (see Section 9)
Safe ("yes" or "no", see Section 9.2.1)Idempotent ("yes" or "no", see
Section 9.2.2)Pointer to specification text Values to be added to this
namespace require IETF Review (see [RFC8126], Section 4.8).
16.1.2. Considerations for New Methods
Standardized methods are generic; that is, they are potentially applicable
to any resource, not just one particular media type, kind of resource, or
application. As such, it is preferred that new methods be registered in a
document that isn't specific to a single application or data format, since
orthogonal technologies deserve orthogonal specification.
Since message parsing (Section 6) needs to be independent of method
semantics (aside from responses to HEAD), definitions of new methods cannot
change the parsing algorithm or prohibit the presence of content on either
the request or the response message. Definitions of new methods can specify
that only a zero-length content is allowed by requiring a Content-Length
header field with a value of "0". Likewise, new methods cannot use the
special host:port and asterisk forms of request target that are allowed for
CONNECT and OPTIONS, respectively (Section 7.1). A full URI in absolute form
is needed for the target URI, which means either the request target needs to
be sent in absolute form or the target URI will be reconstructed from the
request context in the same way it is for other methods. A new method
definition needs to indicate whether it is safe (Section 9.2.1), idempotent
(Section 9.2.2), cacheable (Section 9.2.3), what semantics are to be
associated with the request content (if any), and what refinements the
method makes to header field or status code semantics. If the new method is
cacheable, its definition ought to describe how, and under what conditions,
a cache can store a response and use it to satisfy a subsequent request. The
new method ought to describe whether it can be made conditional (Section
13.1) and, if so, how a server responds when the condition is false.
Likewise, if the new method might have some use for partial response
semantics (Section 14.2), it ought to document this, too.
Note: Avoid defining a method name that starts with "M-", since that prefix
might be misinterpreted as having the semantics assigned to it by
[RFC2774].
EXTENSIBLITY:
16. Extending HTTP
HTTP defines a number of generic extension points that can be used to
introduce capabilities to the protocol without introducing a new version,
including methods, status codes, field names, and further extensibility
points within defined fields, such as authentication schemes and cache
directives (see Cache-Control extensions in Section 5.2.3 of [CACHING]).
Because the semantics of HTTP are not versioned, these extension points are
persistent; the version of the protocol in use does not affect their
semantics.
Version-independent extensions are discouraged from depending on or
interacting with the specific version of the protocol in use. When this is
unavoidable, careful consideration needs to be given to how the extension
can interoperate across versions. Additionally, specific versions of HTTP
might have their own extensibility points, such as transfer codings in
HTTP/1.1 (Section 6.1 of [HTTP/1.1]) and HTTP/2 SETTINGS or frame types
([HTTP/2]). These extension points are specific to the version of the
protocol they occur within. Version-specific extensions cannot override or
modify the semantics of a version-independent mechanism or extension point
(like a method or header field) without explicitly being allowed by that
protocol element. For example, the CONNECT method (Section 9.3.6) allows
this. These guidelines assure that the protocol operates correctly and
predictably, even when parts of the path implement different versions of
HTTP.
16.1. Method Extensibility
16.1.1. Method Registry
The "Hypertext Transfer Protocol (HTTP) Method Registry", maintained by IANA
at , registers method names.
HTTP method registrations MUST include the following fields:
Method Name (see Section 9)
Safe ("yes" or "no", see Section 9.2.1)Idempotent ("yes" or "no", see
Section 9.2.2)Pointer to specification text Values to be added to this
namespace require IETF Review (see [RFC8126], Section 4.8).
16.1.2. Considerations for New Methods
Standardized methods are generic; that is, they are potentially applicable
to any resource, not just one particular media type, kind of resource, or
application. As such, it is preferred that new methods be registered in a
document that isn't specific to a single application or data format, since
orthogonal technologies deserve orthogonal specification.
Since message parsing (Section 6) needs to be independent of method
semantics (aside from responses to HEAD), definitions of new methods cannot
change the parsing algorithm or prohibit the presence of content on either
the request or the response message. Definitions of new methods can specify
that only a zero-length content is allowed by requiring a Content-Length
header field with a value of "0". Likewise, new methods cannot use the
special host:port and asterisk forms of request target that are allowed for
CONNECT and OPTIONS, respectively (Section 7.1). A full URI in absolute form
is needed for the target URI, which means either the request target needs to
be sent in absolute form or the target URI will be reconstructed from the
request context in the same way it is for other methods. A new method
definition needs to indicate whether it is safe (Section 9.2.1), idempotent
(Section 9.2.2), cacheable (Section 9.2.3), what semantics are to be
associated with the request content (if any), and what refinements the
method makes to header field or status code semantics. If the new method is
cacheable, its definition ought to describe how, and under what conditions,
a cache can store a response and use it to satisfy a subsequent request. The
new method ought to describe whether it can be made conditional (Section
13.1) and, if so, how a server responds when the condition is false.
Likewise, if the new method might have some use for partial response
semantics (Section 14.2), it ought to document this, too.
Note:
Avoid defining a method name that starts with "M-", since that prefix
might be misinterpreted as having the semantics assigned to it by [RFC2774].
16.2. Status Code Extensibility
16.2.1. Status Code Registry
The "Hypertext Transfer Protocol (HTTP) Status Code Registry", maintained by
IANA at , registers status code numbers.
A registration MUST include the following fields:
Status Code (3 digits)
Short DescriptionPointer to specification text Values to be added to the
HTTP status code namespace require IETF Review (see [RFC8126], Section
4.8).
16.2.2. Considerations for New Status Codes
When it is necessary to express semantics for a response that are not
defined by current status codes, a new status code can be registered. Status
codes are generic; they are potentially applicable to any resource, not just
one particular media type, kind of resource, or application of HTTP. As
such, it is preferred that new status codes be registered in a document that
isn't specific to a single application.
New status codes are required to fall under one of the categories defined in
Section 15. To allow existing parsers to process the response message, new
status codes cannot disallow content, although they can mandate a zero
-length content. Proposals for new status codes that are not yet widely
deployed ought to avoid allocating a specific number for the code until
there is clear consensus that it will be registered; instead, early drafts
can use a notation such as "4NN", or "3N0" .. "3N9", to indicate the class
of the proposed status code(s) without consuming a number prematurely. The
definition of a new status code ought to explain the request conditions that
would cause a response containing that status code (e.g., combinations of
request header fields and/or method(s)) along with any dependencies on
response header fields (e.g., what fields are required, what fields can
modify the semantics, and what field semantics are further refined when used
with the new status code). By default, a status code applies only to the
request corresponding to the response it occurs within. If a status code
applies to a larger scope of applicability -- for example, all requests to
the resource in question or all requests to a server -- this must be
explicitly specified. When doing so, it should be noted that not all clients
can be expected to consistently apply a larger scope because they might not
understand the new status code. The definition of a new final status code
ought to specify whether or not it is heuristically cacheable. Note that any
response with a final status code can be cached if the response has explicit
freshness information. A status code defined as heuristically cacheable is
allowed to be cached without explicit freshness information. Likewise, the
definition of a status code can place constraints upon cache behavior if the
must-understand cache directive is used. See [CACHING] for more information.
Finally, the definition of a new status code ought to indicate whether the
content has any implied association with an identified resource (Section
6.4.2).
16.3. Field Extensibility
HTTP's most widely used extensibility point is the definition of new header
and trailer fields.
New fields can be defined such that, when they are understood by a
recipient, they override or enhance the interpretation of previously defined
fields, define preconditions on request evaluation, or refine the meaning of
responses. However, defining a field doesn't guarantee its deployment or
recognition by recipients. Most fields are designed with the expectation
that a recipient can safely ignore (but forward downstream) any field not
recognized. In other cases, the sender's ability to understand a given field
might be indicated by its prior communication, perhaps in the protocol
version or fields that it sent in prior messages, or its use of a specific
media type. Likewise, direct inspection of support might be possible through
an OPTIONS request or by interacting with a defined well-known URI [RFC8615]
if such inspection is defined along with the field being introduced.
16.3.1. Field Name Registry
The "Hypertext Transfer Protocol (HTTP) Field Name Registry" defines the
namespace for HTTP field names.
Any party can request registration of an HTTP field. See Section 16.3.2 for
considerations to take into account when creating a new HTTP field. The
"Hypertext Transfer Protocol (HTTP) Field Name Registry" is located at .
Registration requests can be made by following the instructions located
there or by sending an email to the "ietf-http-wg@w3.org" mailing list.
Field names are registered on the advice of a designated expert (appointed
by the IESG or their delegate). Fields with the status 'permanent' are
Specification Required ([RFC8126], Section 4.6). Registration requests
consist of the following information:
Field name:
The requested field name. It MUST conform to the field-name syntax
defined in Section 5.1, and it SHOULD be restricted to just letters, digits,
and hyphen ('-') characters, with the first character being a letter.
Status:
"permanent", "provisional", "deprecated", or "obsoleted".
Specification document(s):
Reference to the document that specifies the field, preferably including
a URI that can be used to retrieve a copy of the document. Optional but
encouraged for provisional registrations. An indication of the relevant
section(s) can also be included, but is not required.
And optionally:
Comments:
Additional information, such as about reserved entries.
The expert(s) can define additional fields to be collected in the registry,
in consultation with the community.
Standards-defined names have a status of "permanent". Other names can also
be registered as permanent if the expert(s) finds that they are in use, in
consultation with the community. Other names should be registered as
"provisional". Provisional entries can be removed by the expert(s) if -- in
consultation with the community -- the expert(s) find that they are not in
use. The expert(s) can change a provisional entry's status to permanent at
any time. Note that names can be registered by third parties (including the
expert(s)) if the expert(s) determines that an unregistered name is widely
deployed and not likely to be registered in a timely manner otherwise.
16.3.2. Considerations for New Fields
HTTP header and trailer fields are a widely used extension point for the
protocol. While they can be used in an ad hoc fashion, fields that are
intended for wider use need to be carefully documented to ensure
interoperability.
In particular, authors of specifications defining new fields are advised to
consider and, where appropriate, document the following aspects:
Under what conditions the field can be used; e.g., only in responses or
requests, in all messages, only on responses to a particular request method,
etc.
Whether the field semantics are further refined by their context, such as
their use with certain request methods or status codes.The scope of
applicability for the information conveyed. By default, fields apply only to
the message they are associated with, but some response fields are designed
to apply to all representations of a resource, the resource itself, or an
even broader scope. Specifications that expand the scope of a response field
will need to carefully consider issues such as content negotiation, the time
period of applicability, and (in some cases) multi-tenant server
deployments.Under what conditions intermediaries are allowed to insert,
delete, or modify the field's value.If the field is allowable in trailers;
by default, it will not be (see Section 6.5.1).Whether it is appropriate or
even required to list the field name in the Connection header field (i.e.,
if the field is to be hop-by-hop; see Section 7.6.1).Whether the field
introduces any additional security considerations, such as disclosure of
privacy-related data. Request header fields have additional considerations
that need to be documented if the default behavior is not appropriate:
If it is appropriate to list the field name in a Vary response header field
(e.g., when the request header field is used by an origin server's content
selection algorithm; see Section 12.5.5).
If the field is intended to be stored when received in a PUT request (see
Section 9.3.4).If the field ought to be removed when automatically
redirecting a request due to security concerns (see Section 15.4).
16.3.2.1. Considerations for New Field Names
Authors of specifications defining new fields are advised to choose a short
but descriptive field name. Short names avoid needless data transmission;
descriptive names avoid confusion and "squatting" on names that might have
broader uses.
To that end, limited-use fields (such as a header confined to a single
application or use case) are encouraged to use a name that includes that use
(or an abbreviation) as a prefix; for example, if the Foo Application needs
a Description field, it might use "Foo-Desc"; "Description" is too generic,
and "Foo-Description" is needlessly long. While the field-name syntax is
defined to allow any token character, in practice some implementations place
limits on the characters they accept in field-names. To be interoperable,
new field names SHOULD constrain themselves to alphanumeric characters, "-",
and ".", and SHOULD begin with a letter. For example, the underscore ("_")
character can be problematic when passed through non-HTTP gateway interfaces
(see Section 17.10). Field names ought not be prefixed with "X-"; see
[BCP178] for further information. Other prefixes are sometimes used in HTTP
field names; for example, "Accept-" is used in many content negotiation
headers, and "Content-" is used as explained in Section 6.4. These prefixes
are only an aid to recognizing the purpose of a field and do not trigger
automatic processing.
16.3.2.2. Considerations for New Field Values
A major task in the definition of a new HTTP field is the specification of
the field value syntax: what senders should generate, and how recipients
should infer semantics from what is received.
Authors are encouraged (but not required) to use either the ABNF rules in
this specification or those in [RFC8941] to define the syntax of new field
values. Authors are advised to carefully consider how the combination of
multiple field lines will impact them (see Section 5.3). Because senders
might erroneously send multiple values, and both intermediaries and HTTP
libraries can perform combination automatically, this applies to all field
values -- even when only a single value is anticipated. Therefore, authors
are advised to delimit or encode values that contain commas (e.g., with the
quoted-string rule of Section 5.6.4, the String data type of [RFC8941], or a
field-specific encoding). This ensures that commas within field data are not
confused with the commas that delimit a list value. For example, the Content
-Type field value only allows commas inside quoted strings, which can be
reliably parsed even when multiple values are present. The Location field
value provides a counter-example that should not be emulated: because URIs
can include commas, it is not possible to reliably distinguish between a
single value that includes a comma from two values. Authors of fields with a
singleton value (see Section 5.5) are additionally advised to document how
to treat messages where the multiple members are present (a sensible default
would be to ignore the