4 Network Working Group M. Nottingham
5 Internet-Draft Rackspace
6 Updates: 2616 (if approved) R. Fielding
7 Intended status: Standards Track Adobe
8 Expires: August 7, 2012 February 4, 2012
11 Additional HTTP Status Codes
12 draft-nottingham-http-new-status-04
16 This document specifies additional HyperText Transfer Protocol (HTTP)
17 status codes for a variety of common situations.
19 Editorial Note (To be removed by RFC Editor before publication)
21 Distribution of this document is unlimited. Although this is not a
22 work item of the HTTPbis Working Group, comments should be sent to
23 the Hypertext Transfer Protocol (HTTP) mailing list at
24 ietf-http-wg@w3.org [1], which may be joined by sending a message
25 with subject "subscribe" to ietf-http-wg-request@w3.org [2].
27 Discussions of the HTTPbis Working Group are archived at
28 <http://lists.w3.org/Archives/Public/ietf-http-wg/>.
32 This Internet-Draft is submitted in full conformance with the
33 provisions of BCP 78 and BCP 79.
35 Internet-Drafts are working documents of the Internet Engineering
36 Task Force (IETF). Note that other groups may also distribute
37 working documents as Internet-Drafts. The list of current Internet-
38 Drafts is at http://datatracker.ietf.org/drafts/current/.
40 Internet-Drafts are draft documents valid for a maximum of six months
41 and may be updated, replaced, or obsoleted by other documents at any
42 time. It is inappropriate to use Internet-Drafts as reference
43 material or to cite them other than as "work in progress."
45 This Internet-Draft will expire on August 7, 2012.
49 Copyright (c) 2012 IETF Trust and the persons identified as the
50 document authors. All rights reserved.
55 Nottingham & Fielding Expires August 7, 2012 [Page 1]
57 Internet-Draft Additional HTTP Status Codes February 2012
60 This document is subject to BCP 78 and the IETF Trust's Legal
61 Provisions Relating to IETF Documents
62 (http://trustee.ietf.org/license-info) in effect on the date of
63 publication of this document. Please review these documents
64 carefully, as they describe your rights and restrictions with respect
65 to this document. Code Components extracted from this document must
66 include Simplified BSD License text as described in Section 4.e of
67 the Trust Legal Provisions and are provided without warranty as
68 described in the Simplified BSD License.
73 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3
74 2. Requirements . . . . . . . . . . . . . . . . . . . . . . . . . 3
75 3. 428 Precondition Required . . . . . . . . . . . . . . . . . . . 3
76 4. 429 Too Many Requests . . . . . . . . . . . . . . . . . . . . . 4
77 5. 431 Request Header Fields Too Large . . . . . . . . . . . . . . 4
78 6. 511 Network Authentication Required . . . . . . . . . . . . . . 5
79 7. Security Considerations . . . . . . . . . . . . . . . . . . . . 6
80 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . . 7
81 9. References . . . . . . . . . . . . . . . . . . . . . . . . . . 8
82 9.1. Normative References . . . . . . . . . . . . . . . . . . . 8
83 9.2. Informative References . . . . . . . . . . . . . . . . . . 8
84 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . . 8
85 Appendix B. Issues Raised by Captive Portals . . . . . . . . . . . 8
86 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 9
111 Nottingham & Fielding Expires August 7, 2012 [Page 2]
113 Internet-Draft Additional HTTP Status Codes February 2012
118 This document specifies additional HTTP [RFC2616] status codes for a
119 variety of common situations, to improve interoperability and avoid
120 confusion when other, less precise status codes are used.
122 Note that these status codes are optional; servers cannot be required
123 to support them. However, because clients will treat unknown status
124 codes as a generic error of the same class (e.g., 499 is treated as
125 400 if it is not recognized), they can be safely deployed by existing
126 servers (see [RFC2616] Section 6.1.1 for more information).
131 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
132 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
133 document are to be interpreted as described in [RFC2119].
136 3. 428 Precondition Required
138 The 428 status code indicates that the origin server requires the
139 request to be conditional.
141 Its typical use is to avoid the "lost update" problem, where a client
142 GETs a resource's state, modifies it, and PUTs it back to the server,
143 when meanwhile a third party has modified the state on the server,
144 leading to a conflict. By requiring requests to be conditional, the
145 server can assure that clients are working with the correct copies.
147 Responses using this status code SHOULD explain how to resubmit the
148 request successfully. For example:
150 HTTP/1.1 428 Precondition Required
151 Content-Type: text/html
155 <title>Precondition Required</title>
158 <h1>Precondition Required</h1>
159 <p>This request is required to be conditional;
160 try using "If-Match".</p>
167 Nottingham & Fielding Expires August 7, 2012 [Page 3]
169 Internet-Draft Additional HTTP Status Codes February 2012
172 Responses with the 428 status code MUST NOT be stored by a cache.
175 4. 429 Too Many Requests
177 The 429 status code indicates that the user has sent too many
178 requests in a given amount of time ("rate limiting").
180 The response representations SHOULD include details explaining the
181 condition, and MAY include a Retry-After header indicating how long
182 to wait before making a new request.
186 HTTP/1.1 429 Too Many Requests
187 Content-Type: text/html
192 <title>Too Many Requests</title>
195 <h1>Too Many Requests</h1>
196 <p>I only allow 50 requests per hour to this Web site per
197 logged in user. Try again soon.</p>
201 Note that this specification does not define how the origin server
202 identifies the user, nor how it counts requests. For example, an
203 origin server that is limiting request rates can do so based upon
204 counts of requests on a per-resource basis, across the entire server,
205 or even among a set of servers. Likewise, it might identify the user
206 by its authentication credentials, or a stateful cookie.
208 Responses with the 429 status code MUST NOT be stored by a cache.
211 5. 431 Request Header Fields Too Large
213 The 431 status code indicates that the server is unwilling to process
214 the request because its header fields are too large. The request MAY
215 be resubmitted after reducing the size of the request header fields.
217 It can be used both when the set of request header fields in total
218 are too large, and when a single header field is at fault. In the
219 latter case, the response representation SHOULD specify which header
223 Nottingham & Fielding Expires August 7, 2012 [Page 4]
225 Internet-Draft Additional HTTP Status Codes February 2012
232 HTTP/1.1 431 Request Header Fields Too Large
233 Content-Type: text/html
237 <title>Request Header Fields Too Large</title>
240 <h1>Request Header Fields Too Large</h1>
241 <p>The "Example" header was too large.</p>
245 Responses with the 431 status code MUST NOT be stored by a cache.
248 6. 511 Network Authentication Required
250 The 511 status code indicates that the client needs to authenticate
251 to gain network access.
253 The response representation SHOULD contain a link to a resource that
254 allows the user to submit credentials (e.g. with a HTML form).
256 Note that the 511 response SHOULD NOT contain a challenge or the
257 login interface itself, because browsers would show the login
258 interface as being associated with the originally requested URL,
259 which may cause confusion.
261 The 511 status SHOULD NOT be generated by origin servers; it is
262 intended for use by intercepting proxies that are interposed as a
263 means of controlling access to the network.
265 Responses with the 511 status code MUST NOT be stored by a cache.
267 6.1. The 511 Status Code and Captive Portals
269 The 511 status code is designed to mitigate problems caused by
270 "captive portals" to software (especially non-browser agents) that is
271 expecting a response from the server that a request was made to, not
272 the intervening network infrastructure. It is not intended to
273 encouraged deployment of captive portals, only to limit the damage
279 Nottingham & Fielding Expires August 7, 2012 [Page 5]
281 Internet-Draft Additional HTTP Status Codes February 2012
284 A network operator wishing to require some authentication, acceptance
285 of terms or other user interaction before granting access usually
286 does so by identifing clients who have not done so ("unknown
287 clients") using their MAC addresses.
289 Unknown clients then have all traffic blocked, except for that on TCP
290 port 80, which is sent to a HTTP server (the "login server")
291 dedicated to "logging in" unknown clients, and of course traffic to
292 the login server itself.
294 For example, a user agent might connect to a network and make the
295 following HTTP request on TCP port 80:
297 GET /index.htm HTTP/1.1
298 Host: www.example.com
300 Upon receiving such a request, the login server would generate a 511
303 HTTP/1.1 511 Network Authentication Required
304 Content-Type: text/html
308 <title>Network Authentication Required</title>
309 <meta http-equiv="refresh"
310 content="0; url=https://login.example.net/">
313 <p>You need to <a href="https://login.example.net/">
314 authenticate with the local network</a> in order to gain
319 Here, the 511 status code assures that non-browser clients will not
320 interpret the response as being from the origin server, and the META
321 HTML element redirects the user agent to the login server.
324 7. Security Considerations
326 7.1. 428 Precondition Required
328 The 428 status code is optional; clients cannot rely upon its use to
329 prevent "lost update" conflicts.
335 Nottingham & Fielding Expires August 7, 2012 [Page 6]
337 Internet-Draft Additional HTTP Status Codes February 2012
340 7.2. 429 Too Many Requests
342 When a server is under attack or just receiving a very large number
343 of requests from a single party, responding to each with a 429 status
344 code will consume resources.
346 Therefore, servers are not required to use the 429 status code; when
347 limiting resource usage, it may be more appropriate to just drop
348 connections, or take other steps.
350 7.3. 431 Request Header Fields Too Large
352 Servers are not required to use the 431 status code; when under
353 attack, it may be more appropriate to just drop connections, or take
356 7.4. 511 Network Authentication Required
358 In common use, a response carrying the 511 status code will not come
359 from the origin server indicated in the request's URL. This presents
360 many security issues; e.g., an attacking intermediary may be
361 inserting cookies into the original domain's name space, may be
362 observing cookies or HTTP authentication credentials sent from the
363 user agent, and so on.
365 However, these risks are not unique to the 511 status code; in other
366 words, a captive portal that is not using this status code introduces
369 Also, note that captive portals using this status code on an SSL or
370 TLS connection (commonly, port 443) will generate a certificate error
374 8. IANA Considerations
376 The HTTP Status Codes Registry should be updated with the following
380 o Description: Precondition Required
381 o Specification: [ this document ]
384 o Description: Too Many Requests
385 o Specification: [ this document ]
391 Nottingham & Fielding Expires August 7, 2012 [Page 7]
393 Internet-Draft Additional HTTP Status Codes February 2012
397 o Description: Request Header Fields Too Large
398 o Specification: [ this document ]
401 o Description: Network Authentication Required
402 o Specification: [ this document ]
407 9.1. Normative References
409 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
410 Requirement Levels", BCP 14, RFC 2119, March 1997.
412 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H.,
413 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext
414 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999.
416 9.2. Informative References
418 [RFC4791] Daboo, C., Desruisseaux, B., and L. Dusseault,
419 "Calendaring Extensions to WebDAV (CalDAV)", RFC 4791,
422 [RFC4918] Dusseault, L., "HTTP Extensions for Web Distributed
423 Authoring and Versioning (WebDAV)", RFC 4918, June 2007.
427 [1] <mailto:ietf-http-wg@w3.org>
429 [2] <mailto:ietf-http-wg-request@w3.org?subject=subscribe>
432 Appendix A. Acknowledgements
434 Thanks to Jan Algermissen and Julian Reschke for their suggestions
438 Appendix B. Issues Raised by Captive Portals
440 Since clients cannot differentiate between a portal's response and
441 that of the HTTP server that they intended to communicate with, a
442 number of issues arise. The 511 status code is intended to help
443 mitigate some of them.
447 Nottingham & Fielding Expires August 7, 2012 [Page 8]
449 Internet-Draft Additional HTTP Status Codes February 2012
452 One example is the "favicon.ico"
453 <http://en.wikipedia.org/wiki/Favicon> commonly used by browsers to
454 identify the site being accessed. If the favicon for a given site is
455 fetched from a captive portal instead of the intended site (e.g.,
456 because the user is unauthenticated), it will often "stick" in the
457 browser's cache (most implementations cache favicons aggressively)
458 beyond the portal session, so that it seems as if the portal's
459 favicon has "taken over" the legitimate site.
461 Another browser-based issue comes about when P3P
462 <http://www.w3.org/TR/P3P/> is supported. Depending on how it is
463 implemented, it's possible a browser might interpret a portal's
464 response for the p3p.xml file as the server's, resulting in the
465 privacy policy (or lack thereof) advertised by the portal being
466 interpreted as applying to the intended site. Other Web-based
467 protocols such as WebFinger
468 <http://code.google.com/p/webfinger/wiki/WebFingerProtocol>, CORS
469 <http://www.w3.org/TR/cors/> and OAuth
470 <http://tools.ietf.org/html/draft-ietf-oauth-v2> may also be
471 vulnerable to such issues.
473 Although HTTP is most widely used with Web browsers, a growing number
474 of non-browsing applications use it as a substrate protocol. For
475 example, WebDAV [RFC4918] and CalDAV [RFC4791] both use HTTP as the
476 basis (for remote authoring and calendaring, respectively). Using
477 these applications from behind a captive portal can result in
478 spurious errors being presented to the user, and might result in
479 content corruption, in extreme cases.
481 Similarly, other non-browser applications using HTTP can be affected
482 as well; e.g., widgets <http://www.w3.org/TR/widgets/>, software
483 updates, and other specialised software such as Twitter clients and
484 the iTunes Music Store.
486 It should be noted that it's sometimes believed that using HTTP
487 redirection to direct traffic to the portal addresses these issues.
488 However, since many of these uses "follow" redirects, this is not a
498 URI: http://www.mnot.net/
503 Nottingham & Fielding Expires August 7, 2012 [Page 9]
505 Internet-Draft Additional HTTP Status Codes February 2012
509 Adobe Systems Incorporated
514 Email: fielding@gbiv.com
515 URI: http://roy.gbiv.com/
559 Nottingham & Fielding Expires August 7, 2012 [Page 10]