Back to list
308

Permanent Redirect

3xx Redirection

.md

ELI5

This moved for good, and you should keep using the same kind of request when you switch to the new address.

Server perspective

Use 308 for permanent redirects when the redirected request must preserve the original method and body.

When to use

  • •Return 308 for durable API or route migrations where non-GET requests must keep their semantics
  • •Prefer 308 over 301 when clients should permanently update their target URI without method ambiguity
  • •Permanent endpoint migrations where POST, PUT, PATCH, or DELETE semantics must be preserved
  • •Long-term API version or hostname changes that should keep the same request method
  • •Permanent route cleanup where non-GET clients should update to a new URI

How to respond

  • •Include a Location header with the new permanent URI
  • •Keep the new target stable enough that clients can safely update stored endpoints

Headers to consider

  • •Location
  • •Cache-Control

Response body

  • •A body is optional, but the permanent target must be clear from Location

Server-side pitfalls

  • •Do not use 308 for temporary rerouting
  • •Do not choose 301 if preserving non-GET methods is part of the contract
  • •Temporary redirects; use 307
  • •Cases where method preservation is irrelevant and a simple 301 is sufficient
  • •Flows where the next step should be an indirect GET or HEAD retrieval; use 303

Examples

Permanent API migration

Request:PUT https://api.example.test/api/v1/users/123
Response:308 Permanent Redirect # Headers Location: https://api.example.test/api/v2/users/123

The client should update the endpoint and resend the same PUT to the new permanent URI.

Permanent webhook path change

Request:POST https://api.example.test/hooks/incoming
Response:308 Permanent Redirect # Headers Location: https://api.example.test/webhooks/incoming

The sender should keep POST semantics while moving permanently to the new route.

References

Related Status Codes

301

Moved Permanently

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

307

Temporary Redirect

Go to this other address for now, and send the exact same kind of request there.