301 - Moved Permanently
HTTP 301 Moved Permanently means the resource has a new permanent URI and future requests should use it.
Last reviewed: February 15, 2026|Source-backed guidance under our editorial policy
Start Here
Use the closest compare guide, playbook, or adjacent error page to narrow the decision faster before you start changing production systems.
This page is part of the Error Reference library. Learn more about the project or report a correction.
What Does Moved Permanently Mean?
The resource has permanently moved, so clients and crawlers should stop using the old URI and treat the new location as canonical.
Common Causes
- -Rewrite chain applies http-to-https and host canonicalization separately, producing permanent redirect from legacy URI.
- -API endpoint was permanently moved after version retirement, and clients continue calling deprecated path.
- -Proxy trailing-slash normalization enforces canonical route and emits permanent redirect for old format.
How to Fix Moved Permanently
- 1Validate the Location target is the intended canonical URI and resolves with expected content.
- 2Update internal links, sitemaps, SDK defaults, and API clients to use the new permanent URI directly.
- 3Remove chained redirects and align CDN or origin cache policy for permanent migration behavior.
Step-by-Step Diagnosis for Moved Permanently
- 1Capture original URI, method, and
Locationtarget for every 301 emission path. - 2Verify redirect map has one canonical destination and no conflicting host/path rewrites.
- 3Check client and crawler handling for method preservation and caching behavior.
- 4Retest with direct and redirected calls to validate one-hop permanent migration behavior.
Redirect Map and Canonical Destination Integrity
- -Audit redirect chains for multi-hop or conflicting rules (example:
/a -> /b -> /cinstead of one-hop/a -> /c). - -Verify canonical host/path policy consistency (example: www and non-www rules conflict by environment).
Client, Cache, and Method Behavior Validation
- -Inspect cache persistence of permanent redirects (example: stale 301 cached by browser after rollback).
- -Validate method semantics for non-GET requests through redirect path (example: legacy client rewrites POST unexpectedly).
Implementation Examples
curl -i -X GET https://api.example.com/v1/resource
# Response:
# HTTP/1.1 301 Moved Permanently
# {"error":"Moved Permanently","code":"301"}const response = await fetch('https://api.example.com/v1/resource', {
method: 'GET',
headers: { 'Accept': 'application/json' }
});
if (response.status === 301) {
console.error('Handle 301 Moved Permanently');
}import requests
response = requests.get(
'https://api.example.com/v1/resource',
headers={'Accept': 'application/json'}
)
if response.status_code == 301:
print('Handle 301 Moved Permanently')Seen in Production
Domain migration from legacy host to canonical host
Frequency: common
Example: Requests to old domain return 301 to new domain, but one region still chains through intermediate host.
Fix: Consolidate redirect rules into single canonical target and verify parity across all edge regions.
Permanent API version move with stale client cache
Frequency: rare
Example: Old endpoint 301 cached aggressively; rollback causes clients to keep hitting outdated target.
Fix: Plan cache-aware migration windows and validate rollback-safe redirect TTL strategy.
Debugging Tools
- -curl -IL to inspect redirect hops and Location headers
- -Browser DevTools Network tab (Preserve log enabled)
- -CDN and reverse-proxy access logs
- -Redirect-chain checks in CI
How to Verify the Fix
- -Request old URIs and confirm they produce a single 301 hop to the canonical destination.
- -Validate crawler, browser, and API clients resolve directly to the new URI after cache refresh cycles.
- -Monitor redirect-chain metrics and old-URI traffic to confirm permanent migration stabilization.
How to Prevent Recurrence
- -Maintain a canonical URL registry and enforce it in edge, application, and documentation pipelines.
- -Add migration tests that fail on multi-hop redirects, loops, or conflicting host and path rewrites.
- -Schedule redirect deprecation reviews so temporary transitions do not become accidental long-term chains.
Pro Tip
- -version redirect maps like database migrations so every permanent move is auditable and reversible during incident response.
Official References
Provider Context
This guidance is specific to HTTP services. Always validate implementation details against official provider documentation before deploying to production.