Skip to content
3xx · redirectSent by Proxy | App | CDN

308Permanent Redirect

This address has moved for good, and requests must be repeated at the new one unchanged.

How you get a 308

An API client POSTs to the old http address. The proxy sends 308 pointing at https. The client repeats the request there, and it is still a POST with the same body.

Who sends itProxy · App · CDN

  1. Browser
  2. CDN
  3. Proxy
  4. App
  5. DB

Typically the proxy or CDN for site-wide rules that must also work for API calls, such as http to https. The app sends it when an endpoint has moved for good.

In short

What a 308 Permanent Redirect means

A 308 Permanent Redirect combines two promises. Like 301, it says the address has changed for good and clients should use the new one from now on, and may remember it. Like 307, it forbids changing the request: a POST is repeated as a POST with the same body. It exists because a 301 lets clients turn a POST into a GET, which silently breaks API calls and form submissions that hit a redirect. It is typically sent by a proxy or CDN for rules that apply to every request, such as forcing https on an API. The cost is the same as for any permanent redirect: once clients have stored it, changing the server does not reach them. It was first defined in RFC 7538 and is now part of RFC 9110.

When you see a 308

  1. 1A rule forces https or a canonical host, written so that API calls survive it.

    How to check: Send a POST to the old address and confirm Location and the status.

    curl -si -X POST http://api.example.com/v1/items -d '{}' | grep -iE '^HTTP|location'
  2. 2An API endpoint was renamed for good and old clients are pointed at the new path.

    How to check: Check that the client library follows redirects for POST; some refuse unless told to.

  3. 3A hosting platform redirects to its canonical domain with 308 by default.

    How to check: Compare the host in Location with the one you called.

Retry or not?

Nothing to retry · Follow Location

Nothing failed. Repeat the same request at the address in Location and use that address from now on.

Headers that matter

Location
The new permanent address.
Cache-Control
A 308 is cacheable by default, like 301. Set a lifetime while you are still testing the rule.

In the real world

RFC vs real deployments

RFC 9110 defines 308 as 301 without permission to change the method. Support is not quite as universal as for 301: very old clients and some HTTP libraries do not recognise 308, or will not resend a body without being configured to. For public web pages that are only ever fetched with GET, 301 and 308 behave the same; the difference only shows on requests with a body.

Seen in a real outage

Permanent means remembered. The mobile carrier Three learned it with a 301: browsers kept following a redirect to an error page long after the reason for it had gone. A 308 is stored in exactly the same way.

Your turn

Which code is it?

You force https on an API with a 301. GET requests keep working, but POST requests from some clients now arrive as GET with no body. What fixes it?

Often confused with

308 questions

What is the difference between 301 and 308?
Both are permanent. A 301 lets clients turn a POST into a GET when they follow it. A 308 requires the same method and body to be sent to the new address.
What is the difference between 307 and 308?
Both keep the method and body. A 307 is temporary, so clients keep using the original address. A 308 is permanent, so clients switch to the new address and may remember it.
Who sends a 308?
Typically the proxy or CDN, for site-wide rules that also need to work for API calls. Some hosting platforms use it for their own domain redirects.

Sources: RFC 9110: 308 Permanent Redirect (section 15.4.9) ↗ · RFC 7538: 308 Permanent Redirect, original definition ↗ · Report a problem

Diagrams are our own simulations. All wording is original and paraphrases the linked sources.

Practise this in the DNS / HTTP track

Two-minute animated lessons, then boss fights from real outages. Free, no account needed.

Start the track