RFC 6585

RFC 6585: Additional HTTP Status Codes 🎀

okay bestie, this one is a whole vibe 🦋 It's RFC 6585, titled "Additional HTTP Status Codes," and it's Standards Track, which means it's an official Internet standard, not just a fun idea someone had. It was written by M. Nottingham (Rackspace) and R. Fielding (Adobe) and published in April 2012. Its ISSN is 2070-1721. It updates RFC 2616, which is the old HTTP/1.1 spec, so this doc adds to it without replacing it. 💅

Abstract ✨

This doc adds some brand-new HTTP status codes for situations that come up all the time. The goal is to make things more interoperable and to stop people from getting confused when the server uses a vaguer status code that doesn't really say what happened. 🌸

Status of This Memo 📜

This is an Internet Standards Track document. ✨

It's a product of the Internet Engineering Task Force (IETF), so it represents what the IETF community agreed on. It got public review and was approved for publication by the Internet Engineering Steering Group (IESG). If you want more info on Internet Standards, check out Section 2 of RFC 5741.

If you want the latest status of this doc, any errata, or a way to send feedback, go to http://www.rfc-editor.org/info/rfc6585. 🦋

Copyright Notice 💜

The copyright belongs to the IETF Trust and the people listed as authors, dated 2012, and all rights are reserved. 🔒

This doc is covered by BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) as they stood when it was published. Read those carefully, because they spell out what you can and can't do with the doc. If you pull Code Components out of this doc, they have to include the Simplified BSD License text described in Section 4.e of the Trust Legal Provisions, and they come with no warranty, as the Simplified BSD License says. 🫶

Table of Contents 🧚

1. Introduction ....................................................2
2. Requirements ....................................................2
3. 428 Precondition Required .......................................2
4. 429 Too Many Requests ...........................................3
5. 431 Request Header Fields Too Large .............................4
6. 511 Network Authentication Required .............................4
7. Security Considerations .........................................6
8. IANA Considerations .............................................7
9. References ......................................................7
Appendix A. Acknowledgements .......................................9
Appendix B. Issues Raised by Captive Portals .......................9

1. Introduction 🌈

This doc adds new HTTP [RFC2616] status codes for common situations. The point is better interoperability and less confusion when a server would otherwise use a less precise status code. 💖

These status codes are optional, so servers cannot be required to support them. Here's the good news though: clients treat any unknown status code as a generic error in the same class. So if a client sees a 499 it doesn't recognize, it treats it like a 400. That means existing servers can safely deploy these new codes. (See [RFC2616] Section 6.1.1 for more info.) 🍓

2. Requirements 📌

Here's where we decide what the key words mean. In this doc, the key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" are to be interpreted as described in [RFC2119]. Those capitalized words are the ones with real weight, so keep an eye on them. 👑

3. 428 Precondition Required 🔥

The 428 status code tells you that the origin server needs the request to be conditional. 🙈

Here's why it matters. Picture a client that GETs a resource's state, edits it, and PUTs it back. Meanwhile, a third party changed the state on the server, so now there's a conflict and someone's update gets lost. Requiring requests to be conditional lets the server make sure everyone is working with the correct copies. That's the whole "lost update" problem, and this code is built to solve it. 💅

Responses using this status code SHOULD explain how to resubmit the request successfully. Here's an example:

HTTP/1.1 428 Precondition Required
Content-Type: text/html
<html>
   <head>
      <title>Precondition Required</title>
   </head>
   <body>
      <h1>Precondition Required</h1>
      <p>This request is required to be conditional;
      try using "If-Match".</p>
   </body>
</html>

Responses with the 428 status code MUST NOT be stored by a cache. Caches, you have been warned! 🚫💜

4. 429 Too Many Requests 🌸

The 429 status code means the user sent too many requests in a given amount of time. This is what people call "rate limiting." ⭐

The response representations SHOULD include details explaining the situation. They MAY also include a Retry-After header that says how long to wait before sending a new request. ⏳

Here's an example:

HTTP/1.1 429 Too Many Requests
Content-Type: text/html
Retry-After: 3600

<html>
   <head>
      <title>Too Many Requests</title>
   </head>
   <body>
      <h1>Too Many Requests</h1>
      <p>I only allow 50 requests per hour to this Web site per
         logged in user.  Try again soon.</p>
   </body>
</html>

Quick note: this spec doesn't say how the origin server figures out who the user is, or how it counts requests. A server limiting rates might count requests per resource, across the whole server, or even across a group of servers. It might identify users by their authentication credentials or by a stateful cookie. It's totally up to the server, bestie. 🧚

Responses with the 429 status code MUST NOT be stored by a cache. 🚫

5. 431 Request Header Fields Too Large 🦋

The 431 status code means the server won't process the request because its header fields are too large. The request MAY be sent again once the size of the request header fields has been reduced. 🎀

This code works two ways. It can mean the whole set of request header fields is too big, or it can mean one specific header field is the problem. In the second case, the response representation SHOULD say which header field was too large. 🔍

Here's an example:

HTTP/1.1 431 Request Header Fields Too Large
Content-Type: text/html

<html>
   <head>
      <title>Request Header Fields Too Large</title>
   </head>
   <body>
      <h1>Request Header Fields Too Large</h1>
      <p>The "Example" header was too large.</p>
   </body>
</html>

Responses with the 431 status code MUST NOT be stored by a cache. Same energy as before, periodt. 💅

6. 511 Network Authentication Required 🔐

The 511 status code means the client has to authenticate to get network access. 🌈

The response representation SHOULD contain a link to a resource where the user can submit credentials, for example with an HTML form. 🍓

Also, the 511 response SHOULD NOT contain a challenge or the login interface itself. Why? Browsers would show the login interface as if it belonged to the URL the user originally asked for, which could be really confusing. 🙃

And the 511 status SHOULD NOT be generated by origin servers. It's meant for intercepting proxies that sit in the middle as a way to control access to the network. 🛡️

Responses with the 511 status code MUST NOT be stored by a cache. 💜

6.1. The 511 Status Code and Captive Portals 🏨

Okay, so the 511 status code exists to fix problems caused by "captive portals." Those are the login pages you hit on airport or café Wi-Fi. The problems hit software (especially non-browser apps) that expects a response from the server it actually requested, not from the network box in the middle. 😭

Here's the important part: this code is NOT meant to encourage captive portals. It's only meant to limit the damage they cause. 🫶

A network operator who wants users to sign in, accept terms, or do some other interaction before granting access usually does it by identifying clients who haven't done that yet ("unknown clients") by their Media Access Control (MAC) addresses. ✨

Unknown clients then get all their traffic blocked, except for TCP port 80 traffic. That traffic goes to an HTTP server (the "login server") that's dedicated to logging in unknown clients. Traffic to the login server itself is allowed too, of course. 🧚

For example, a user agent might connect to a network and send this HTTP request on TCP port 80:

GET /index.htm HTTP/1.1
Host: www.example.com

When the login server gets a request like that, it generates a 511 response:

HTTP/1.1 511 Network Authentication Required
Content-Type: text/html

<html>
   <head>
      <title>Network Authentication Required</title>
      <meta http-equiv="refresh"
            content="0; url=https://login.example.net/">
   </head>
   <body>
      <p>You need to <a href="https://login.example.net/">
      authenticate with the local network</a> in order to gain
      access.</p>
   </body>
</html>

Here's the magic: the 511 status code makes sure non-browser clients won't think the response came from the origin server. And the META HTML element sends the user agent over to the login server. Iconic. 👑🌸

---

To be continued! Part 2 covers Security Considerations, IANA Considerations, References, and the appendices 💖

9.2. Informative References ✨

Okay, now the bibliography for the extra-credit reading 📚🎀. These are the references the document points to but doesn't depend on to work.

   [CORS]      van Kesteren, A., Ed., "Cross-Origin Resource Sharing",
               W3C Working Draft WD-cors-20100727, July 2010,
               <http://www.w3.org/TR/cors/>.

   [Favicon]   Wikipedia, "Favicon", March 2012,
               <http://en.wikipedia.org/w/
               index.php?title=Favicon&oldid=484627550>.

   [OAuth2.0]  Hammer-Lahav, E., Ed., Recordon, D., and D. Hardt, "The
               OAuth 2.0 Authorization Protocol", Work in Progress,
               March 2012.

   [P3P]       Marchiori, M., Ed., "The Platform for Privacy Preferences
               1.0 (P3P1.0) Specification", W3C Recommendation
               REC-P3P-20020416, April 2002,
               <http://www.w3.org/TR/P3P/>.

   [RFC4791]   Daboo, C., Desruisseaux, B., and L. Dusseault,
               "Calendaring Extensions to WebDAV (CalDAV)", RFC 4791,
               March 2007.

   [RFC4918]   Dusseault, L., Ed., "HTTP Extensions for Web Distributed
               Authoring and Versioning (WebDAV)", RFC 4918, June 2007.

   [WIDGETS]   Caceres, M., Ed., "Widget Packaging and XML
               Configuration", W3C Recommendation REC-widgets-20110927,
               September 2011, <http://www.w3.org/TR/widgets/>.

   [WebFinger] WebFinger Project, "WebFingerProtocol (Draft)",
               January 2010, <http://code.google.com/p/webfinger/wiki/
               WebFingerProtocol>.

Appendix A. Acknowledgements 🫶

Big thank-you to Jan Algermissen and Julian Reschke for sharing their suggestions and feedback. You two are literally the reason this is so polished 💖.

Appendix B. Issues Raised by Captive Portals 🌈

Okay, so this is the chaotic part. Clients have no way to tell whether a response came from a captive portal or from the HTTP server they were actually trying to reach 😭. That opens the door to a whole bunch of problems, and the 511 status code is meant to help patch some of them 🩹.

One classic example is the favicon, that tiny icon browsers use to identify the site you're on 🌸. If a site's favicon gets fetched from a captive portal instead of the real site (say, because you aren't logged in yet), it often gets stuck in the browser's cache. Most implementations cache favicons super aggressively, so it can outlive the portal session entirely. The result is that the portal's icon seems to have "taken over" the legit site. Iconic? Not really 💀.

Another browser-side mess happens when the Platform for Privacy Preferences [P3P] is in play. Depending on how it's implemented, a browser might read a portal's response to the p3p.xml file as coming from the actual server. That means whatever privacy policy (or lack of one) the portal advertises could end up being applied to the site you meant to visit 🙈. Other web protocols like WebFinger [WebFinger], Cross-Origin Resource Sharing [CORS], and Open Authorization [OAuth2.0] may be vulnerable to the same kind of trouble too 🔥.

Now, HTTP is mostly known for powering web browsers, but more and more non-browsing apps are using it as their underlying protocol 🧚. Web Distributed Authoring and Versioning (WebDAV) [RFC4918] and Calendaring Extensions to WebDAV (CalDAV) [RFC4791] both build on HTTP for remote authoring and calendaring, respectively. Using these from behind a captive portal can throw spurious errors at the user and, in extreme cases, might even corrupt content 😱.

Other non-browser apps that use HTTP can get caught in this too, like widgets [WIDGETS], software updates, and specialized software such as Twitter clients and the iTunes Music Store 🎧.

Also, you'll sometimes hear people say that using HTTP redirection to send traffic to the portal fixes all of this. Sadly, that's not it, bestie 🙅‍♀️. Lots of these apps "follow" redirects, so that approach isn't a good solution at all.

---

Authors' Addresses 🦋

   Mark Nottingham
   Rackspace

   EMail: mnot@mnot.net
   URI:   http://www.mnot.net/


   Roy T. Fielding
   Adobe Systems Incorporated
   345 Park Ave.
   San Jose, CA  95110
   USA

   EMail: fielding@gbiv.com
   URI:   http://roy.gbiv.com/