What Is Status Code: 308 Permanent Redirect? The Unbreakable Redirect

You're refactoring your API. You've decided that the endpoint POST /api/v1/create-user is poorly named and needs to be changed to the more accurate POST /api/v1/users. This is a permanent, structural change. You know you need a redirect, but you have a critical requirement: any application that POSTs data to the old endpoint must have its data perfectly preserved and forwarded to the new one.

This is a job for a specialized tool. It's not a job for the familiar 301 Moved Permanently, which can be ambiguous. It requires the precision and power of the 308 Permanent Redirect status code.

The 308 is the ultimate guarantee in the HTTP redirect family. It's a permanent, method-preserving, body-preserving, no-nonsense command from the server. It says, "I have moved forever. When you send any request to my old address whether it's a simple GET or a complex POST with data I insist that you resend the exact same request to my new address."

So, what does status code 308 actually mean? How is it different from 301 or 307? And when should you use it in real-world scenarios?

If you're building APIs that handle non-GET requests, understanding 308 is essential for maintaining backward compatibility and ensuring data integrity during migrations.

And before we dive into the technical specifics, if you're managing API endpoints that are evolving, you need a tool that can test these critical, method-sensitive redirects. In this comprehensive blog post, we’ll explore everything you need to know about the 308 Permanent Redirect status code from what it means and how it works to when and why you should use it. Additionally, to help you test and document complex HTTP responses effectively, don’t forget to download Apidog for free, a user-friendly API testing and documentation tool engineered to simplify your workflow and give you deep insights into HTTP status codes like 308.

button

Now, let’s unravel the details behind HTTP status code 308 Permanent Redirect.

The Problem: The 301 Moved Permanently Ambiguity

To understand why 308 was created, we must first look at its predecessor, the 301 Moved Permanently.

The 301 redirect is fantastic for most common web browsing scenarios. However, its original specification had a crucial ambiguity, much like the 302/307 situation. The spec did not explicitly state what should happen to the HTTP method and body of the original request during the redirect.

In practice, many user agents (especially web browsers) would change a POST request to a GET request when following a 301 redirect. The request body would be dropped.

The API Developer's Nightmare Scenario:

A mobile app POSTs JSON data to your old endpoint: POST /old-api {"name": "John"}
Your server responds with: 301 Moved Permanently + Location: /new-api
The mobile app's HTTP library follows the redirect by sending: GET /new-api (with no body)
Your /new-api endpoint, expecting a POST with JSON, receives a GET and returns a 405 Method Not Allowed error.
The mobile app breaks for all its users.

The 308 status code was introduced to solve this problem with absolute precision.

What Does HTTP 308 Permanent Redirect Actually Mean?

The 308 Permanent Redirect status code indicates that the target resource has been assigned a new permanent URI. The key differentiator is that the user agent MUST NOT change the request method used in the original request when it makes the redirected request.

Furthermore, the body of the original request must be preserved and resent.

In simple terms: "The resource has moved forever. Resend the identical request to this new location."

A typical 308 response looks like this:

HTTP/1.1 308 Permanent RedirectLocation: <https://new-api.example.com/v2/usersContent-Type:> text/htmlContent-Length: 147
<html><head><title>308 Permanent Redirect</title></head><body><center><h1>308 Permanent Redirect</h1></center></body></html>

The crucial elements are the status code itself (308) and the Location header. The HTML body is often ignored by automated clients.

Why Redirects Matter in HTTP

Redirects are a fundamental part of the web. They let servers communicate changes in resource location without breaking clients.

Some common use cases include:

Moving from HTTP to HTTPS.
Updating API endpoints without breaking existing clients.
Changing a website’s URL structure during a redesign.
Handling content versioning or reorganization.

Without redirects, developers would constantly face 404 Not Found errors and broken user experiences.

Why Was 308 Permanent Redirect Introduced?

The older 301 status code instructs clients to update URLs permanently. However, browsers historically changed HTTP methods like POST to GET when following 301 redirects, causing unintended behavior like losing form data or unexpected responses.

To address these limitations, the RFC 7538 specification introduced 308 Permanent Redirect to explicitly guarantee that user agents:

Should preserve HTTP methods after redirect
Must not convert POST to GET (or any other method switch)

This makes 308 especially useful in APIs and web applications that require method consistency along the redirection path.

308 vs. 301: The Critical Comparison

This is the most important distinction for API developers.

Feature	`301 Moved Permanently`	`308 Permanent Redirect`
Method Preservation	Not guaranteed. Browsers often change POST to GET.	Guaranteed. The method must be identical (POST remains POST).
Body Preservation	Not guaranteed. The request body is typically dropped.	Guaranteed. The original request body is resent.
Use Case	Perfect for permanent redirects of web page URLs (where the original request is almost always GET).	Essential for permanent redirects of API endpoints that handle POST, PUT, DELETE.
Safety	Potentially unsafe for non-GET methods.	Safe for all HTTP methods.
Analogy	"That shop has a new permanent address. Go check it out." (You go empty-handed).	"The entire factory has relocated. Send all future shipments, exactly as packaged, to this new warehouse address."

When to use which?

Use 301 Moved Permanently when permanently redirecting web page links (e.g., changing a blog post's URL). It's SEO-friendly and works perfectly for GET requests.
Use 308 Permanent Redirect when permanently redirecting API endpoints that receive data (POST, PUT) or other non-GET methods. It guarantees data integrity.

How Does 308 Permanent Redirect Work?

Here’s the typical flow of a 308 redirect:

Client makes a request:

POST /checkout HTTP/1.1
Host: shop.example.com

2. Server responds with 308:

HTTP/1.1 308 Permanent Redirect
Location: <https://secure.example.com/checkout>

3. Client repeats the POST request at the new location, preserving body and headers:

POST /checkout HTTP/1.1
Host: secure.example.com

No method switching. No surprises. Since the redirect is permanent, clients are expected to update bookmarks and internal references accordingly.

Use Cases for 308 Permanent Redirect

308 redirects fit best in scenarios where:

You perform a permanent URL restructuring but want clients to keep using the original HTTP methods.
Your API or web app has POST, PUT, or DELETE endpoints that have changed URLs.
You want to implement SEO-friendly permanent redirects without breaking form submissions.
You need a reliable way to avoid inadvertent method switching caused by older redirect codes.

A Real-World Example: API Migration

Imagine you are versioning your API and need to retire an old endpoint.

The Old System:

Endpoint: POST /v1/orders
Body: { "product_id": "abc123", "quantity": 2 }

The New System:

Endpoint: POST /v2/orders
Body: { "product_id": "abc123", "quantity": 2 } (Same structure)

You want to shut down the v1 server but don't want to break old clients that haven't updated. Your solution is a 308 redirect on the v1 server:

1. The Old Client's Request: A legacy app sends a request to the old endpoint.

POST /v1/orders HTTP/1.1Host: api.example.comContent-Type: application/json
{"product_id": "abc123", "quantity": 2}

2. The 308 Response: The v1 server responds with a redirect to the v2 endpoint.

HTTP/1.1 308 Permanent RedirectLocation: <https://api.example.com/v2/orders>

3. The Preserved Request: The client's HTTP library respects the 308 spec. It resends the exact same POST request with the exact same JSON body to the new location.

POST /v2/orders HTTP/1.1Host: api.example.comContent-Type: application/json
{"product_id": "abc123", "quantity": 2} # The original body is preserved!

4. The Successful Order: The v2 server processes the request and creates the order, returning a 201 Created response. The legacy client works perfectly without any code changes.

This approach provides a seamless and robust migration path for API consumers.

Example: Implementing a 308 Redirect After URL Change

Imagine a REST API where a resource’s URI changed:

Client sends a POST request to http://api.example.com/v1/resource.
Server responds:

textHTTP/1.1 308 Permanent Redirect Location: <https://api.example.com/v2/resource>

3. Browser or client resends the POST request, unchanged, to https://api.example.com/v2/resource.

4. API processes the request as intended.

This preserves the request semantics and ensures smooth migration.

Benefits of 308 Permanent Redirect

Consistency → Guarantees method preservation.
Clarity → Clearly signals a permanent change to clients and search engines.
Safety → Prevents accidental downgrades of POST to GET.
Future-proofing → Works well in modern HTTP/2+ environments.

How to Implement 308 Redirects

Implementation depends on your server or platform.

Apache (.htaccess or config)

textRedirectPermanent 308 /old-path <https://example.com/new-path>

Nginx

textlocation /old-path { return 308 <https://example.com/new-path>; }

Express.js (Node.js)

javascriptapp.post('/old-path', (req, res) => { res.redirect(308, '<https://example.com/new-path>'); });

How Clients Handle 308 Redirects

Because 308 is a relatively new code, client support varies but is widely adopted in modern browsers and HTTP libraries:

Most browsers preserve HTTP methods after 308 redirects.
Older clients might default to GET on permanent redirects testing is essential.
Clients should update URLs in bookmarks and caches after receiving 308.

308 in API Development and Microservices

For APIs and microservices, 308 is a game-changer.

Imagine this:

You’re migrating an API from api.v1.example.com to api.v2.example.com.
Some clients still send POST requests with critical payloads.
With 301, those POSTs might get converted to GETs, breaking everything.
With 308, clients safely resend the POST as intended.

This makes 308 invaluable for mission-critical API traffic.

Testing 308 Redirects with Apidog

Testing this behavior is non-negotiable for a production API. You must ensure that your redirects work correctly and that clients will behave as expected. Apidog is an indispensable tool for this.

With Apidog, you can:

1. Craft a POST Request: Create a request to your old endpoint URL with a specific JSON or XML body.

2. Mock the 308 Response: Configure your server mock to return a 308 status with the new Location header.

3. Validate the Redirected Request: The most crucial step. After sending the request, use Apidog's detailed logs to inspect the second request that was automatically sent.

Did it go to the correct URL in the Location header?
Was the HTTP method still POST?
Was the request body identical to the original?

4. Compare with 301: Run the same test but have the mock return a 301 instead. Observe how Apidog (acting as a standard client) likely changes the method to GET and drops the body. This side-by-side comparison is the best way to understand the practical difference.

5. Test Client Libraries: If you're building an SDK or client, use Apidog to mock the server and ensure your client code correctly handles a 308 response by preserving the method and body.

button

Download Apidog for free to make redirect testing painless and reliable and try mocking a 308 redirect yourself it takes minutes to set up.

SEO Implications

Unlike 301, the 308 code is primarily for APIs, not web pages. Most web crawlers from search engines like Google primarily make GET requests. For them, a 301 and a 308 would have the same effect: they would update their index to the new URL and transfer ranking signals.

However, you should still use 301 for permanent page moves on your website. It is the universally supported and expected standard for HTML content, and its behavior is well-understood by all web crawlers and browsers. Use 308 for the programmatic, data-oriented parts of your system.

Common Pitfalls to Avoid

Using 308 when a temporary redirect is required (use 307 instead).
Misconfiguring servers to incorrectly convert methods on redirect.
Assuming all clients support 308 test robustly across your user base.
Forgetting to update internal links to reflect permanent URL changes.

When Not to Use 308

For temporary redirects, use 307 Temporary Redirect.
When you want the client to switch to GET method after redirect, use 303 See Other.
When no URL change has occurred, avoid redirect codes altogether.

Alternatives to 308 Permanent Redirect

Depending on your needs:

Use 301 for simple permanent redirects where POST/PUT isn’t involved.
Use 307 Temporary Redirect for temporary method-preserving redirects.
Use 302 Found for quick, temporary redirections that don’t impact SEO.

308 is the best fit when you want permanent + method-preserving behavior.

Security Considerations for 308 Redirects

Redirects can be abused if not handled carefully. With 308:

Always use HTTPS in the Location header.
Avoid redirecting to untrusted domains.
Test for open redirect vulnerabilities.

308 is safer than 301 for preserving sensitive methods, but it’s still important to configure it securely.

Conclusion: The Precision Tool for API Evolution

The HTTP 308 Permanent Redirect status code is a specialist tool designed for a specific, critical job: ensuring the integrity of non-GET requests during permanent API migrations. It represents the HTTP protocol's evolution towards greater precision and reliability, closing the dangerous ambiguities of its predecessors.

HTTP status code 308 Permanent Redirect offers a modern, precise way to handle permanent URL changes while preserving HTTP methods, making it invaluable for APIs and web applications that rely on method consistency.

While you may use 301 redirects every day for your website, the 308 is the tool you reach for when the stakes are higher when you need to guarantee that data is not lost, that API clients don't break, and that your backend evolution happens smoothly.

By using 308 correctly, you can improve user experience, preserve the integrity of requests, and protect your SEO investment.

Understanding this distinction is a key differentiator between a developer who understands web basics and one who architects robust, professional systems. And when it's time to implement and test these critical redirects, to test and document your API endpoints especially those involving redirects don’t forget to download Apidog for free. Apidog empowers you to explore HTTP status codes like 308 thoroughly, helping you develop with confidence and clarity.

button