Permanent Redirect

Description

Examples

POST /api/v1/orders HTTP/1.1
Host: api.example.com
Content-Type: application/json
Authorization: Bearer token123

{"product_id": "prod_abc", "quantity": 2, "shipping": "express"}

HTTP/1.1 308 Permanent Redirect
Location: https://api.example.com/api/v2/orders
Content-Type: application/json

{"message": "The /v1/orders endpoint has permanently moved to /v2/orders. Please update your integration.", "new_url": "https://api.example.com/api/v2/orders", "documentation": "https://docs.example.com/migration/v1-to-v2"}

PUT /users/42/profile HTTP/1.1
Host: old-api.example.com
Content-Type: application/json
If-Match: "etag-v7"

{"display_name": "Alice Smith", "bio": "Engineer"}

HTTP/1.1 308 Permanent Redirect
Location: https://new-api.example.com/users/42/profile
Cache-Control: public, max-age=31536000

{"message": "This API has permanently moved to new-api.example.com. All endpoints and methods are preserved."}

POST /webhooks/stripe HTTP/1.1
Host: hooks.old-domain.com
Content-Type: application/json
Stripe-Signature: t=1234,v1=sig...

{"type": "payment_intent.succeeded", "data": {"object": {"id": "pi_abc", "amount": 2000}}}

HTTP/1.1 308 Permanent Redirect
Location: https://hooks.new-domain.com/webhooks/stripe

{"error": "endpoint_moved", "message": "Webhook receiver has permanently moved. Update your Stripe dashboard to use https://hooks.new-domain.com/webhooks/stripe"}

Edge Cases

• •308 REQUIRES the client to preserve the request method AND body. A client that strips the body on redirect is violating the spec — but some older HTTP libraries did exactly this. Always test your HTTP client's redirect behavior with POST bodies.
• •Caching: 308 is cacheable by default (it's permanent). Include Cache-Control headers to control how long clients and intermediaries cache the redirect. A misconfigured cache can make rollbacks impossible if you need to un-redirect.
• •Redirect loops: if /a 308→/b and /b 308→/a, the client is trapped. Servers must maintain a complete redirect map and validate no cycles exist before deploying permanent redirects.
• •Request body size: some proxies and CDNs have body buffering limits. A 308 redirect of a large file upload (POST with 100MB body) may fail at the infrastructure layer because the proxy didn't buffer the original body to replay it at the new location.
• •Authentication headers: per RFC 9110, clients SHOULD strip Authorization headers when following a redirect to a different origin. A 308 from api.example.com to api2.example.com may lose the auth token — the client needs to re-authenticate at the new location.
• •Browser form submissions: if a user submits a form via POST and receives a 308, the browser MUST re-send the POST to the new URL. Unlike 303 (which converts to GET for the redirect target), 308 will cause the form data to be re-submitted — potentially creating duplicate resources if the new endpoint isn't idempotent.
• •SEO impact: search engines treat 308 identically to 301 — link equity passes to the new URL. However, some crawlers may not follow 308 if they only understand the older RFC 2616 status codes. For public-facing pages, 301 is safer; reserve 308 for API endpoints where method preservation matters.

When You'll See This

• →API version sunset — POST /v1/resource permanently moves to POST /v2/resource
• →Domain migration where the old domain's API endpoints permanently redirect to the new domain, preserving PUT/PATCH/DELETE semantics
• →Webhook receiver URL change — third-party services POSTing to your old URL get redirected to the new one while preserving the payload
• →Permanent URL restructuring in a REST API — /users/42/orders moves to /orders?user=42 but must still accept POST for order creation
• →Corporate acquisition — acquired company's API permanently redirects to parent company's API while preserving all HTTP methods
• →Moving from path-based to subdomain-based API routing — POST api.example.com/v2/payments permanently replaces POST example.com/api/v2/payments
• →CDN origin change where mutable endpoints (file uploads via POST) need to follow the new origin without losing the request body

Implementation References

History

Originally defined in RFC 7238 (June 2014) as an experimental status code, then elevated to Standards Track in RFC 7538 (April 2015). Now consolidated into RFC 9110 §15.4.9 (June 2022) as part of the HTTP Semantics reorganization. Created specifically to address the decades-old ambiguity in 301 where user agents changed POST to GET despite no spec requirement to do so.

Related Status Codes

Related Headers

FAQ