RFC 7238

The Hypertext Transfer Protocol Status Code 308 (Permanent Redirect)

📅 published June 2014, from ietf

RFC 7238: The Hypertext Transfer Protocol Status Code 308 (Permanent Redirect) 🎀

Who wrote it: J. Reschke from greenbytes, for the IETF (Internet Engineering Task Force). It's RFC 7238, published June 2014, with ISSN 2070-1721.

Category: Experimental 🧪 This is NOT a Standards Track spec. It's out there for people to look at, try out in code, and evaluate.

Obsoletes/Updates: This document doesn't list anything it obsoletes or updates.

Abstract ✨

Okay so this doc adds one more HTTP status code, 308 (Permanent Redirect). That's the whole pitch 💅

Status of This Memo 📜

Real talk: this doc is not an Internet Standards Track spec. It's published so people can examine it, experiment with it, and evaluate it 🧪

It defines an Experimental Protocol for the Internet community. It's a product of the IETF, it reflects the IETF community's consensus, it got public review, and the IESG (Internet Engineering Steering Group) approved it for publication. Not every IESG-approved doc is a candidate for any level of Internet Standard, so see Section 2 of RFC 5741 if you're curious about that 🤓

Want the current status, errata, or a way to send feedback? Check http://www.rfc-editor.org/info/rfc7238 🔗

Copyright Notice ©️

This doc is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) as they stood on the date it was published. Read those carefully, bestie, because they spell out your rights and restrictions for this document. Code Components pulled out of this doc must include Simplified BSD License text, as described in Section 4.e of the Trust Legal Provisions, and they come with no warranty, per the Simplified BSD License.

Table of Contents 🗺️

1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . . . 2
2.  Notational Conventions  . . . . . . . . . . . . . . . . . . . . 2
3.  308 Permanent Redirect  . . . . . . . . . . . . . . . . . . . . 2
4.  Deployment Considerations . . . . . . . . . . . . . . . . . . . 3
5.  Security Considerations . . . . . . . . . . . . . . . . . . . . 4
6.  IANA Considerations . . . . . . . . . . . . . . . . . . . . . . 4
7.  Acknowledgements  . . . . . . . . . . . . . . . . . . . . . . . 5
8.  References  . . . . . . . . . . . . . . . . . . . . . . . . . . 5
  8.1.  Normative References  . . . . . . . . . . . . . . . . . . . 5
  8.2.  Informative References  . . . . . . . . . . . . . . . . . . 5

1. Introduction 🦋

HTTP has a whole family of status codes for redirecting a request to a different URI ([RFC3986]). Their history is covered in Section 6.4 of [RFC7231], which also sorts the existing codes into four categories.

The first category holds 301 (Moved Permanently), 302 (Found), and 307 (Temporary Redirect). Here's how they break down 👀

+-------------------------------------------+-----------+-----------+
|                                           | Permanent | Temporary |
+-------------------------------------------+-----------+-----------+
| Allows changing the request method from   | 301       | 302       |
| POST to GET                               |           |           |
| Does not allow changing the request       | -         | 307       |
| method from POST to GET                   |           |           |
+-------------------------------------------+-----------+-----------+

So here's the gap 🫣 Section 6.4.7 of [RFC7231] says HTTP doesn't define a permanent version of 307. This spec fills that hole by adding 308, the missing permanent variant (Section 3). It's giving completion 💖

2. Notational Conventions 📝

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC2119].

3. 308 Permanent Redirect 🎀

The 308 (Permanent Redirect) status code says the target resource now has a brand new permanent URI, and any future references to this resource ought to use one of the enclosed URIs 💅

Clients that can edit links ought to automatically re-link references to the effective request URI (Section 5.5 of [RFC7230]) to one or more of the new references the server sent, wherever that's possible ✨

The server SHOULD include a Location header field ([RFC7231], Section 7.1.2) in the response, holding a preferred URI reference for the new permanent URI 🔗 The user agent MAY use the Location field value to redirect automatically. The server's response payload usually has a short hypertext note with a hyperlink to the new URI(s) 🌸

A 308 response is cacheable by default 🧠 That's the case unless the method definition or explicit cache controls say otherwise (see [RFC7234], Section 4.2.2).

Note: This status code is similar to 301 (Moved Permanently) ([RFC7231], Section 6.4.2), except that it does not allow changing the request method from POST to GET.

4. Deployment Considerations 🚀

Here's the tea ☕ Section 6 of [RFC7231] requires recipients to treat unknown 3xx status codes the same way they'd treat status code 300 Multiple Choices ([RFC7231], Section 6.4.1). So servers can't count on automatic redirection working like it does for 301, 302, or 307 😬

That means early use of status code 308 is limited to cases where the server is pretty confident the client understands the new code, or where falling back to status code 300 semantics wouldn't be a problem 🫶 Server implementers are advised not to vary the status code based on request characteristics, like the User-Agent header field ("User-Agent Sniffing"). Doing that usually leads to code that's hard to maintain and hard to debug, and it would also need extra care around caching (meaning setting a "Vary" response header field, as defined in Section 7.1.4 of [RFC7231]) 🙈

Also, lots of existing HTML-based user agents will fake a refresh when they hit an HTML <meta> refresh directive ([HTML]). That makes a handy backup fallback 🧚 Here's an example.

Client request:

GET / HTTP/1.1
Host: example.com

Server response:

HTTP/1.1 308 Permanent Redirect
Content-Type: text/html; charset=UTF-8
Location: http://example.com/new
Content-Length: 454

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
                      "http://www.w3.org/TR/html4/strict.dtd">
<html>
   <head>
      <title>Permanent Redirect</title>
      <meta http-equiv="refresh"
            content="0; url=http://example.com/new">
   </head>
   <body>
      <p>
         The document has been moved to
         <a href="http://example.com/new"
         >http://example.com/new</a>.
      </p>
   </body>
</html>

5. Security Considerations 🚨

Okay, serious moment 🫡 Every security consideration that applies to HTTP redirects also applies to the 308 status code. No exceptions, no skipping (see Section 9 of [RFC7231]). Read that section like your data depends on it, because it does 😭

6. IANA Considerations 📋

The registration below has been added to the "Hypertext Transfer Protocol (HTTP) Status Code Registry" (defined in Section 8.2 of [RFC7231] and located at <http://www.iana.org/assignments/http-status-codes>) 🎉

+-------+--------------------+---------------------------------+
| Value | Description        | Reference                       |
+-------+--------------------+---------------------------------+
| 308   | Permanent Redirect | Section 3 of this specification |
+-------+--------------------+---------------------------------+

7. Acknowledgements 🫶

The definition of the new status code 308 reuses text from the HTTP/1.1 definitions of status codes 301 and 307 🔁

Thanks also to Ben Campbell, Cyrus Daboo, Eran Hammer-Lahav, Bjoern Hoehrmann, Subramanian Moonesamy, Peter Saint-Andre, and Robert Sparks for giving feedback on this document 💜

8. References 📚

8.1. Normative References

[RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
           Requirement Levels", BCP 14, RFC 2119, March 1997.

[RFC3986]  Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
           Resource Identifier (URI): Generic Syntax", STD 66,
           RFC 3986, January 2005.

[RFC7230]  Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer
           Protocol (HTTP/1.1): Message Syntax and Routing",
           RFC 7230, June 2014.

[RFC7231]  Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer
           Protocol (HTTP/1.1): Semantics and Content", RFC 7231,
           June 2014.

[RFC7234]  Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke,
           Ed., "Hypertext Transfer Protocol (HTTP/1.1): Caching",
           RFC 7234, June 2014.

8.2. Informative References

[HTML]     Raggett, D., Le Hors, A., and I. Jacobs, "HTML 4.01
           Specification", W3C Recommendation REC-html401-19991224,
           December 1999,
           <http://www.w3.org/TR/1999/REC-html401-19991224>.

           Latest version available at
           <http://www.w3.org/TR/html401>.

Author's Address 💌

Julian F. Reschke greenbytes GmbH Hafenweg 16 Muenster, NW 48155 Germany

EMail: julian.reschke@greenbytes.de URI: http://greenbytes.de/tech/webdav/

📦 where this page comes from

ietf: rfc7238 2014-06
💖 girlified by claude-haiku-5-5 on 2026-10-18: a language model's rewrite of the original, under its terms