# 301 Moved Permanently

> https://http-status.org/docs/301

**Family:** 3xx Redirection

## Rationale

Permanent redirect; future requests should target the new URI, but older clients may rewrite POST to GET.

## In Plain Terms

This moved for good. Start using the new address from now on.

## Description

The HTTP 301 Moved Permanently status code indicates that the target resource now has a new permanent URI. Clients can reuse that redirect for future requests, but older or browser-style redirect handling can change POST into GET, so 308 is safer when method preservation matters.

## Server Perspective

### Usage
- Return 301 for permanent content moves, canonicalization, and domain migrations
- Prefer 308 instead when redirected POST, PUT, or PATCH requests must keep the same method and body
- Permanent URL or domain migrations
- Canonical URL changes such as path cleanup or site restructuring
- Permanent redirects for GET/HEAD content where method rewriting is not a concern
- Moving old documentation pages to durable replacement locations

### Implementation
- Include a Location header with the new URI
- Keep the target stable so caches, crawlers, and clients are not whipsawed by conflicting permanent redirects

### Common Headers
- Location
- Cache-Control

### Body
- A response body is optional, but the redirect target should be clear from the Location header

### Pitfalls
- Do not use 301 when the move is only temporary
- Do not assume every client will preserve POST on automatic redirects
- Temporary redirects where the original URI should stay canonical
- Non-GET requests where preserving the original method and body matters; use 308 instead
- After a successful write where the follow-up should be a safe retrieval; use 303 See Other instead
- Queued or asynchronous operations where the work has not yet completed; use 202 Accepted instead

## Client Perspective

### Pitfalls
- Do not assume 301 always preserves the original request method

## Examples

### Permanent docs URL change

The old URL should stop being used and future traffic should move to the new path.

**Request:**
```
GET https://api.example.test/guides/http-basics
```

**Response:**
```
301 Moved Permanently
Location: https://api.example.test/docs/http-basics
```

### Domain migration

The resource has a permanent new home and clients can update stored links.

**Request:**
```
GET https://api.example.test/pricing
```

**Response:**
```
301 Moved Permanently
Location: https://example.com/pricing
```

## Related Codes

- [302 Found](/docs/302.md)
- [307 Temporary Redirect](/docs/307.md)
- [308 Permanent Redirect](/docs/308.md)