Orchestrator-workers on HTTP 301 vs 308

HTTP Status Codes 301 and 308: Key Differences

HTTP status codes 301 (Moved Permanently) and 308 (Permanent Redirect) are both used to indicate that a requested resource has been permanently moved to a new URI. However, they differ significantly in how they handle the request method and body during the redirect, and this difference was the motivation for creating 308.

What Each Status Code Means

Both 301 and 308 indicate that the target resource has been assigned a new permanent URI. When a client receives either code, the Location header directs the client to the new resource location, and future references to the old URI should use the new one.

How Clients Handle Request Methods and Bodies

This is the critical difference between the two codes.

For 301 responses: User agents are permitted to change the request method from POST to GET for the subsequent request. This flexibility was built in for historical compatibility reasons, but it means that POST requests (and their bodies) might be converted to GET requests when following a 301 redirect. The request body may be lost if the method is changed.

For 308 responses: The request method and body are not changed. The client must preserve both the original HTTP method and the request body when following a 308 redirect. This provides an unambiguous way to perform permanent redirects while guaranteeing that non-GET operations remain unchanged.

Cacheability

Both status codes are heuristically cacheable by default. Unless otherwise indicated by the method definition or explicit cache control headers, either a 301 or 308 response can be cached by the client or intermediary caches.

Where Each Is Specified

301 (Moved Permanently) is specified in RFC 9110 (HTTP Semantics), Section 15.4.2, which is the current standard for HTTP semantics.

308 (Permanent Redirect) was originally introduced in RFC 7538 and is now also included in RFC 9110, Section 15.4.9. RFC 7538 was created specifically to address the ambiguity introduced by 301's historical behavior, providing a permanent redirect status code that guarantees method and body preservation.

{
  "evidence": [
    {
      "claim": "301 indicates the target resource has been assigned a new permanent URI",
      "quote": "The 301 (Moved Permanently) status code indicates that the target resource has been assigned a new permanent URI and any future references to this resource ought to use one of the enclosed URIs.",
      "url": "https://www.rfc-editor.org/rfc/rfc9110.html"
    },
    {
      "claim": "308 indicates the target resource has been assigned a new permanent URI",
      "quote": "The 308 (Permanent Redirect) status code indicates that the target resource has been assigned a new permanent URI and any future references to this resource ought to use one of the enclosed URIs.",
      "url": "https://www.rfc-editor.org/rfc/rfc9110.html"
    },
    {
      "claim": "301 allows user agents to change request method from POST to GET for historical reasons",
      "quote": "For historical reasons, a user agent MAY change the request method from POST to GET for the subsequent request.",
      "url": "https://www.rfc-editor.org/rfc/rfc9110.html"
    },
    {
      "claim": "308 does not allow changing the request method from POST to GET",
      "quote": "This status code is similar to 301 (Moved Permanently) ([RFC7231], Section 6.4.2), except that it does not allow changing the request method from POST to GET.",
      "url": "https://www.rfc-editor.org/rfc/rfc7538.html"
    },
    {
      "claim": "308 preserves both request method and body in the redirected request",
      "quote": "The request method and the body will not be modified by the client in the redirected request.",
      "url": "https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Status/308"
    },
    {
      "claim": "301 is heuristically cacheable by default",
      "quote": "A 301 response is heuristically cacheable; i.e., unless otherwise indicated by the method definition or explicit cache controls (see Section 4.2.2 of [CACHING]).",
      "url": "https://www.rfc-editor.org/rfc/rfc9110.html"
    },
    {
      "claim": "308 is heuristically cacheable by default",
      "quote": "A 308 response is heuristically cacheable; i.e., unless otherwise indicated by the method definition or explicit cache controls (see Section 4.2.2 of [CACHING]).",
      "url": "https://www.rfc-editor.org/rfc/rfc9110.html"
    },
    {
      "claim": "301 is specified in RFC 9110 Section 15.4.2",
      "quote": "15.4.2. 301 Moved Permanently",
      "url": "https://www.rfc-editor.org/rfc/rfc9110.html"
    },
    {
      "claim": "308 is specified in RFC 7538",
      "quote": "The Hypertext Transfer Protocol Status Code 308 (Permanent Redirect)",
      "url": "https://www.rfc-editor.org/rfc/rfc7538.html"
    },
    {
      "claim": "308 is also specified in RFC 9110 Section 15.4.9",
      "quote": "15.4.9. 308 Permanent Redirect",
      "url": "https://www.rfc-editor.org/rfc/rfc9110.html"
    }
  ]
}