Tech

Explainer

Updated

What does the HTTP 301 status code mean?

Key facts

The server is expected to name the new address in a Location header field, and RFC 9110 says the user agent may use it to redirect automatically.

The HTTP 301 status code means Moved Permanently: under RFC 9110, Section 15.4.2, the resource a client asked for has been given a new permanent address, and future references to it ought to use the new one. The specification puts it this way: "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."

Where the new address comes from

RFC 9110 says the server SHOULD generate a Location header field in a 301 response containing a preferred URI reference for the new permanent URI, and the user agent MAY use that value to redirect automatically. The same section says the response content usually contains a short hypertext note with a link to the new URI.

The Location header field holds a single URI reference. For 3xx responses, it refers to the preferred target resource for automatically redirecting the request, and a relative reference is resolved against the original target URI. If the Location value in a redirect has no fragment (the part after "#"), the same section says the user agent MUST treat it as inheriting the fragment of the original reference.

Permanent references

Section 15.4.2 says the server is suggesting that a user agent with link-editing capability can permanently replace references to the old URI with the new one. The specification adds that this suggestion is usually ignored unless the user agent is actively editing references, the connection is secured, and the origin server is a trusted authority for the content being edited.

POST requests and 301

RFC 9110 notes that, for historical reasons, a user agent MAY change the request method from POST to GET for the request that follows a 301, and that the 308 (Permanent Redirect) code can be used when that behavior is undesired. The introduction to the 3xx class explains the history: HTTP/1.0 first defined 301 and 302 as method-preserving, early user agents split on whether to redirect POST as POST or as GET, practice converged on GET, and 307 and 308 were later added to mark method-preserving redirects without ambiguity.

How 301 compares with 302, 307 and 308

The four redirect codes below are defined in RFC 9110, and its introduction to the 3xx class says each indicates the resource might be available at a different URI provided by the Location header field, with 307 and 308 added to mark method-preserving redirects.

CodeMoveMethod on redirect
301 Moved PermanentlyPermanentPOST may become GET
302 FoundTemporaryPOST may become GET
307 Temporary RedirectTemporaryMethod preserved
308 Permanent RedirectPermanentMethod preserved

For 302, the specification says the resource resides temporarily under a different URI and the client ought to keep using the original URI for future requests. For 307, it says the same about a temporary location and adds that the user agent MUST NOT change the request method if it redirects automatically. Section 15.4.9 describes 308 as a permanent move in the same words it uses for 301, and the note to 301 names 308 as the code to use when a change from POST to GET is undesired.

Caching

RFC 9110 says a 301 response is heuristically cacheable, unless otherwise indicated by the method definition or explicit cache controls. The 308 section says the same of a 308 response.

Where 301 is defined

The IANA HTTP Status Code Registry lists 301 as Moved Permanently and points to RFC 9110, Section 15.4.2 as its reference. RFC 9110 was published in June 2022 as STD 97 and obsoletes earlier HTTP specifications, including RFC 7231 and RFC 7538. The IETF Datatracker lists it as an Internet Standard.

Have another question?