Permanent Redirect

Overview

308 Permanent Redirect announces that a resource has permanently moved to a new URL while requiring the client to re-issue the request with the original HTTP method and body unchanged. In short, it is the method-preserving version of 301.

Because 301 was historically sometimes handled by switching POST to GET, 308 is the accurate code for permanently moving non-GET requests such as POST and PUT.

When it happens

• Use it for API version migrations (v1→v2) or permanent endpoint moves where write requests must keep their method and body when relocated.
• It fits permanently changing a domain or path while preserving form POSTs or API calls exactly.

Request / Response example

PUT /v1/items/9 HTTP/1.1
Host: api.example.com
Content-Type: application/json

{"name":"Widget"}

HTTP/1.1 308 Permanent Redirect
Location: https://api.example.com/v2/items/9
Content-Length: 0

(client re-sends the SAME PUT with its body to the new URL, permanently)

In code

# permanently move /v1/* to /v2/* keeping method + body
location /v1/ {
    return 308 /v2/$uri;
}

app.all('/v1/items/:id', (req, res) => {
  res.redirect(308, `/v2/items/${req.params.id}`);
});

Notes

• As a permanent redirect it is cached by browsers, so a misconfiguration is hard to undo — test with 307 before committing.
• For a permanent move of a simple page where method preservation is not needed, the older and widely supported 301 is fine.
• Use 307 for temporary moves instead of 308, and 303 when a switch to GET is desired.

Related status codes

Related headers

Specification