307 vs 308 redirects: handling redirects in APIs without losing the body

301 and 302 can turn a POST into a GET and drop your data. 307 and 308 keep the method and body. Learn when to use each, and how API clients handle them.

· 6 min read · By the Spot Downtime team

You move an API endpoint, add a redirect, and clients start failing in odd ways. Writes vanish, a POST becomes a GET, or a client refuses to follow the redirect at all. The cause is usually the redirect status code: for web pages 301 and 302 are fine, but for APIs the method matters, and that is what 307 and 308 are for.

The problem with 301 and 302

Early browsers handled 301 and 302 on a POST by repeating the request as a GET and dropping the body. Specifications later allowed that behavior, and it became the de facto standard. So with a 301 or 302, what a client does with a POST depends on the client. Some switch to GET, some repeat the POST, some stop.

For a web page that is harmless. For an API it means a payment, an order or a webhook delivery can silently turn into a read, and the data is lost.

The four redirect codes side by side

  • 301 Moved Permanently: permanent, and clients may change POST to GET.
  • 302 Found: temporary, and clients may change POST to GET.
  • 307 Temporary Redirect: temporary, and the client must repeat the same method and body.
  • 308 Permanent Redirect: permanent, and the client must repeat the same method and body.

Use 307 and 308 whenever the method must survive. Choose between them by whether the move is temporary or permanent, the same way you would choose between 302 and 301.

There is also 303 See Other, which tells the client to fetch a different URL with GET afterward. It is the right answer after a form submission or an async job creation, where you want the client to read a result. Not to repeat the write.

Where you will meet 307 and 308

HTTP to HTTPS

Redirecting http:// to https:// with a 301 can break POSTs from clients that downgrade to GET. A 308 keeps the method. The better fix is for clients to call HTTPS directly, since the first request to the plain URL already sends the body in the clear.

Browsers and HSTS

If a site sends the HSTS header, Chrome shows an internal 307 Internal Redirect from http:// to https:// without any network request. That is browser behavior, not your server, so you will see it in dev tools but not in your logs.

Trailing slashes and renamed routes

Frameworks that redirect /users to /users/ (or the reverse) often use a 301, 302 or 307 depending on the framework and version. Next.js, for example, uses 308 for permanent redirects in its config and 307 for temporary ones. Check what your framework sends rather than assuming.

API versioning and domain moves

Moving api.old.com to api.new.com is the textbook 308: permanent, and every method must keep working.

How API clients behave

Client defaults vary, and several surprise people:

  • curl does not follow redirects unless you pass -L. With -L, a POST redirected by 301 or 302 becomes a GET; 307 and 308 keep it. Use --post301 and --post302 to keep the POST for those.
  • fetch follows redirects by default (redirect: "follow"). You can set "manual" or "error".
  • Many HTTP libraries do not forward the Authorization header when a redirect goes to a different host. This is a security measure, and it shows up as a 401 after a cross-domain 308.
  • Webhook senders often don't follow redirects at all, so a moved webhook URL just fails.
bash
# See the redirect without following it
curl -i -X POST https://api.example.com/v1/orders -d '{"sku":"A1"}'

# HTTP/1.1 308 Permanent Redirect
# Location: https://api.example.com/v2/orders

# Follow it, keeping the POST
curl -i -L -X POST https://api.example.com/v1/orders \
  -H "Content-Type: application/json" -d '{"sku":"A1"}'

Serving redirects correctly

Always include a Location header with an absolute or valid relative URL. In nginx:

nginx
# Permanent, method preserved
location /v1/ {
    return 308 https://api.example.com/v2$request_uri;
}

# Temporary, method preserved
location /maintenance-target/ {
    return 307 https://backup.example.com$request_uri;
}

Keep $request_uri so the path and query string survive. Test with a POST, not only a GET, because a GET test passes with any of the four codes.

Redirects are not a migration plan

For an API, a redirect is a safety net. Announce the change, give clients a deprecation period, and consider returning Deprecation and Sunset headers while the old route still works. Don't rely on every client to follow a 308 correctly.

Monitoring redirects

Redirect chains and loops are easy to introduce in a deploy. A monitor that checks the final status after following redirects will say "up" even when every request takes three hops, or when the target quietly moved. Check that the endpoint you care about answers directly with a 200 and the expected content, and watch for loops (see ERR_TOO_MANY_REDIRECTS). For APIs, see how to monitor an API.

HTTP headers checkerInspect a URL's status code and Location header.

Get new guides by email

Practical posts on monitoring, outages, error fixes and on-call, when they're published. No spam.

Unsubscribe from any email with one click. See our privacy policy.

Keep reading