301 Moved Permanently

HTTP response status code 301 Moved Permanently is returned by the server to indicate that the resource has been given a new permanent location.

The HTTP response is cacheable by default. If the default behavior needs to be overridden then the HTTP response must include the appropriate HTTP caching headers.

Table of Contents

Usage
Example
Code references
Takeaway
See also

Usage

When the 301 Moved Permanently status code is received, clients are expected to update their stored links to the new URI. The new URI is specified by the Location HTTP header and can be used by the client for automatic redirection.

This message might be sent by servers that have migrated to a new domain, or have reorganized their internal file structure, and do not plan on reverting to the former URI.

Note

301 Moved Permanently status code allows for the client to change the HTTP request. For example, if the original HTTP request is a HTTP POST request then the follow-up may be a HTTP GET request. This differs from the 308 Permanent Redirect status code, which requires that an identical request be sent in HTTP response.

Example

In the example, the client attempts to retrieve an HTML resource. The server responds to say that the resource has permanently moved to a new URI and includes it in the Location HTTP header. Client-side, a message is presented in the message body to suggest updating the relevant bookmarks, however this is seldom visible in modern browsers which straight away redirect to the new location.

Request

GET /news.html HTTP/1.1
Host: www.example.re

Response

HTTP/1.1 301 Moved Permanently
Location: http//www.example.re/feeds/news.html
Content-Type: text/html; charset=UTF-8
Content-Length: 150

<h1>The Newsfeed has moved</h1>
<body>
The newsfeed has moved permanently to <a href=/feeds/news.html>here</a>. Please update your bookmarks.
</body>

Code references

.NET

HttpStatusCode.MovedPermanently

Rust

http::StatusCode::MOVED_PERMANENTLY

Rails

:moved_permanently

http.StatusMovedPermanently

Symfony

Response::HTTP_MOVED_PERMANENTLY

Python3.5+

http.HTTPStatus.MOVED_PERMANENTLY

Java

java.net.HttpURLConnection.HTTP_MOVED_PERM

Apache HttpComponents Core

org.apache.hc.core5.http.HttpStatus.SC_MOVED_PERMANENTLY

Angular

@angular/common/http/HttpStatusCode.MovedPermanently

Takeaway

The 301 Moved Permanently status code indicates that the resource has moved to a new location that is specified within the HTTP response. Clients are expected to update their internal data accordingly.