diff --git a/CHANGELOG.md b/CHANGELOG.md
index ab676530..e052c3db 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -8,7 +8,8 @@
 
 ## Changes since v7.14.1
 
-- [#3314](https://github.com/oauth2-proxy/oauth2-proxy/pull/3314) revert: fix: skip provider button auth only redirect (#3309)
+- [#3314](https://github.com/oauth2-proxy/oauth2-proxy/pull/3314) revert: fix: skip provider button auth only redirect (#3309) (@StefanMarkmann / @tuunit)
+- [#3315](https://github.com/oauth2-proxy/oauth2-proxy/pull/3315) docs: clarify browser vs API routes for nginx auth_request redirects (@StefanMarkmann)
 
 # V7.14.1
 
diff --git a/contrib/local-environment/nginx.conf b/contrib/local-environment/nginx.conf
index ffb5f8e2..15005bf6 100644
--- a/contrib/local-environment/nginx.conf
+++ b/contrib/local-environment/nginx.conf
@@ -18,17 +18,20 @@ server {
 
   auth_request /internal-auth/oauth2/auth;
 
-  # If the auth_request denies the request (401), redirect to the sign_in page
-  # and include the final rd URL back to the user's original request.
-  error_page 401 =403 http://oauth2-proxy.oauth2-proxy.localhost/oauth2/sign_in?rd=$scheme://$host$request_uri;
-
-  # Alternatively send the request to `start` to skip the provider button
-  # error_page 401 = http://oauth2-proxy.oauth2-proxy.localhost/oauth2/start?rd=$scheme://$host$request_uri;
+  # On 401, redirect to the sign_in page via a named location
+  # This ensures a proper 302 redirect that browsers will follow
+  error_page 401 = @oauth2_signin;
 
   location / {
     proxy_pass http://httpbin/;
   }
 
+  # Named location for OAuth2 sign-in redirect
+  # Returns a proper 302 that works with --skip-provider-button
+  location @oauth2_signin {
+    return 302 http://oauth2-proxy.oauth2-proxy.localhost/oauth2/sign_in?rd=$scheme://$host$request_uri;
+  }
+
   # auth_request must be a URI so this allows an internal path to then proxy to
   # the real auth_request path.
   # The trailing /'s are required so that nginx strips the prefix before proxying.
@@ -52,18 +55,20 @@ server {
   location / {
     auth_request /internal-auth/oauth2/auth;
 
-    # If the auth_request denies the request (401), redirect to the sign_in page
-    # and include the final rd URL back to the user's original request.
-    error_page 401 =403 http://oauth2-proxy.oauth2-proxy.localhost/oauth2/sign_in?rd=$scheme://$host$request_uri;
-
-    # Alternatively send the request to `start` to skip the provider button
-    # error_page 401 = http://oauth2-proxy.oauth2-proxy.localhost/oauth2/start?rd=$scheme://$host$request_uri;
-
+    # On 401, redirect to the sign_in page via a named location
+    # This ensures a proper 302 redirect that browsers will follow
+    error_page 401 = @oauth2_signin;
 
     root   /usr/share/nginx/html;
     index  index.html index.htm;
   }
 
+  # Named location for OAuth2 sign-in redirect
+  # Returns a proper 302 that works with --skip-provider-button
+  location @oauth2_signin {
+    return 302 http://oauth2-proxy.oauth2-proxy.localhost/oauth2/sign_in?rd=$scheme://$host$request_uri;
+  }
+
   # redirect server error pages to the static page /50x.html
   error_page   500 502 503 504  /50x.html;
   location = /50x.html {
diff --git a/docs/docs/configuration/integrations/nginx.md b/docs/docs/configuration/integrations/nginx.md
index a36ed762..ca6402a9 100644
--- a/docs/docs/configuration/integrations/nginx.md
+++ b/docs/docs/configuration/integrations/nginx.md
@@ -43,7 +43,7 @@ server {
 
   location / {
     auth_request /oauth2/auth;
-    error_page 401 =403 /oauth2/sign_in;
+    error_page 401 = @oauth2_signin;
 
     # pass information via X-User and X-Email headers to backend,
     # requires running with --set-xauthrequest flag
@@ -82,9 +82,76 @@ server {
     proxy_pass http://backend/;
     # or "root /path/to/site;" or "fastcgi_pass ..." etc
   }
+
+  # Named location for handling OAuth2 sign-in redirects
+  # This ensures the browser receives a proper 302 redirect that it will follow
+  location @oauth2_signin {
+    return 302 /oauth2/sign_in?rd=$scheme://$host$request_uri;
+  }
 }
 ```
 
+### Understanding the `error_page` redirect pattern
+
+The `auth_request` directive expects the authentication endpoint (`/oauth2/auth`) to return:
+- **2xx**: Request is authenticated, allow access
+- **401 or 403**: Request is not authenticated, deny access
+
+When a 401 is returned, nginx triggers the `error_page` directive. The recommended pattern uses a **named location** (`@oauth2_signin`) that returns a proper **302 redirect**:
+
+```nginx
+error_page 401 = @oauth2_signin;
+
+location @oauth2_signin {
+  return 302 /oauth2/sign_in?rd=$scheme://$host$request_uri;
+}
+```
+
+:::warning Avoid `error_page 401 =403` with sign_in
+Some older configurations use `error_page 401 =403 /oauth2/sign_in`. While this works for displaying the sign-in page, it returns a **403 status code** with a `Location` header. Browsers do not automatically follow redirects on 403 responses, which can cause issues when using `--skip-provider-button=true` (users see a "Found." link instead of being automatically redirected).
+
+The named location pattern above ensures the browser receives a standard **302 redirect** that works correctly with all oauth2-proxy configurations.
+:::
+
+### Browser vs API Routes
+
+:::important When to use redirects
+Redirecting authentication failures (302 to `/oauth2/sign_in`) should **only be used for browser-facing routes**. API or machine clients should receive a plain 401/403 response without redirect.
+:::
+
+#### Browser-facing routes (HTML, UI)
+
+For interactive browser routes where users should be redirected to sign in:
+
+```nginx
+location / {
+  auth_request /oauth2/auth;
+  error_page 401 = @oauth2_signin;
+  proxy_pass http://backend/;
+}
+
+location @oauth2_signin {
+  return 302 /oauth2/sign_in?rd=$scheme://$host$request_uri;
+}
+```
+
+#### API / Machine routes (no redirect)
+
+For API endpoints where clients expect a 401/403 status code (not a redirect):
+
+```nginx
+location /api/ {
+  auth_request /oauth2/auth;
+  error_page 401 =401;  # Pass through the 401 status
+  proxy_pass http://backend/;
+}
+```
+
+This ensures:
+- ✅ Browsers get a redirect and smooth login flow
+- ✅ API clients fail fast with appropriate HTTP status codes
+- ✅ `/oauth2/auth` remains a pure boolean oracle (2xx/401)
+
 When you use ingress-nginx in Kubernetes, you can configure the same behavior with the following annotations on your Ingress resource:
 
 ```yaml
diff --git a/docs/versioned_docs/version-7.10.x/configuration/integration.md b/docs/versioned_docs/version-7.10.x/configuration/integration.md
index c57cfa6b..a5afeda4 100644
--- a/docs/versioned_docs/version-7.10.x/configuration/integration.md
+++ b/docs/versioned_docs/version-7.10.x/configuration/integration.md
@@ -33,9 +33,15 @@ server {
     proxy_pass_request_body           off;
   }
 
+  # Named location for handling OAuth2 sign-in redirects
+  # This ensures the browser receives a proper 302 redirect that it will follow
+  location @oauth2_signin {
+    return 302 /oauth2/sign_in?rd=$scheme://$host$request_uri;
+  }
+
   location / {
     auth_request /oauth2/auth;
-    error_page 401 =403 /oauth2/sign_in;
+    error_page 401 = @oauth2_signin;
 
     # pass information via X-User and X-Email headers to backend,
     # requires running with --set-xauthrequest flag
@@ -77,6 +83,68 @@ server {
 }
 ```
 
+### Understanding the `error_page` redirect pattern
+
+The `auth_request` directive expects the authentication endpoint (`/oauth2/auth`) to return:
+- **2xx**: Request is authenticated, allow access
+- **401 or 403**: Request is not authenticated, deny access
+
+When a 401 is returned, nginx triggers the `error_page` directive. The recommended pattern uses a **named location** (`@oauth2_signin`) that returns a proper **302 redirect**:
+
+
+```nginx
+error_page 401 = @oauth2_signin;
+
+location @oauth2_signin {
+  return 302 /oauth2/sign_in?rd=$scheme://$host$request_uri;
+}
+```
+
+:::warning Avoid `error_page 401 =403` with sign_in
+Some older configurations use `error_page 401 =403 /oauth2/sign_in`. While this works for displaying the sign-in page, it returns a **403 status code** with a `Location` header. Browsers do not automatically follow redirects on 403 responses, which can cause issues when using `--skip-provider-button=true` (users see a "Found." link instead of being automatically redirected).
+
+The named location pattern above ensures the browser receives a standard **302 redirect** that works correctly with all oauth2-proxy configurations.
+:::
+
+### Browser vs API Routes
+
+:::important When to use redirects
+Redirecting authentication failures (302 to `/oauth2/sign_in`) should **only be used for browser-facing routes**. API or machine clients should receive a plain 401/403 response without redirect.
+:::
+
+#### Browser-facing routes (HTML, UI)
+
+For interactive browser routes where users should be redirected to sign in:
+
+```nginx
+location / {
+  auth_request /oauth2/auth;
+  error_page 401 = @oauth2_signin;
+  proxy_pass http://backend/;
+}
+
+location @oauth2_signin {
+  return 302 /oauth2/sign_in?rd=$scheme://$host$request_uri;
+}
+```
+
+#### API / Machine routes (no redirect)
+
+For API endpoints where clients expect a 401/403 status code (not a redirect):
+
+```nginx
+location /api/ {
+  auth_request /oauth2/auth;
+  error_page 401 =401;  # Pass through the 401 status
+  proxy_pass http://backend/;
+}
+```
+
+This ensures:
+- ✅ Browsers get a redirect and smooth login flow
+- ✅ API clients fail fast with appropriate HTTP status codes
+- ✅ `/oauth2/auth` remains a pure boolean oracle (2xx/401)
+
 When you use ingress-nginx in Kubernetes, you can configure the same behavior with the following annotations on your Ingress resource:
 
 ```yaml
diff --git a/docs/versioned_docs/version-7.11.x/configuration/integration.md b/docs/versioned_docs/version-7.11.x/configuration/integration.md
index c57cfa6b..a5afeda4 100644
--- a/docs/versioned_docs/version-7.11.x/configuration/integration.md
+++ b/docs/versioned_docs/version-7.11.x/configuration/integration.md
@@ -33,9 +33,15 @@ server {
     proxy_pass_request_body           off;
   }
 
+  # Named location for handling OAuth2 sign-in redirects
+  # This ensures the browser receives a proper 302 redirect that it will follow
+  location @oauth2_signin {
+    return 302 /oauth2/sign_in?rd=$scheme://$host$request_uri;
+  }
+
   location / {
     auth_request /oauth2/auth;
-    error_page 401 =403 /oauth2/sign_in;
+    error_page 401 = @oauth2_signin;
 
     # pass information via X-User and X-Email headers to backend,
     # requires running with --set-xauthrequest flag
@@ -77,6 +83,68 @@ server {
 }
 ```
 
+### Understanding the `error_page` redirect pattern
+
+The `auth_request` directive expects the authentication endpoint (`/oauth2/auth`) to return:
+- **2xx**: Request is authenticated, allow access
+- **401 or 403**: Request is not authenticated, deny access
+
+When a 401 is returned, nginx triggers the `error_page` directive. The recommended pattern uses a **named location** (`@oauth2_signin`) that returns a proper **302 redirect**:
+
+
+```nginx
+error_page 401 = @oauth2_signin;
+
+location @oauth2_signin {
+  return 302 /oauth2/sign_in?rd=$scheme://$host$request_uri;
+}
+```
+
+:::warning Avoid `error_page 401 =403` with sign_in
+Some older configurations use `error_page 401 =403 /oauth2/sign_in`. While this works for displaying the sign-in page, it returns a **403 status code** with a `Location` header. Browsers do not automatically follow redirects on 403 responses, which can cause issues when using `--skip-provider-button=true` (users see a "Found." link instead of being automatically redirected).
+
+The named location pattern above ensures the browser receives a standard **302 redirect** that works correctly with all oauth2-proxy configurations.
+:::
+
+### Browser vs API Routes
+
+:::important When to use redirects
+Redirecting authentication failures (302 to `/oauth2/sign_in`) should **only be used for browser-facing routes**. API or machine clients should receive a plain 401/403 response without redirect.
+:::
+
+#### Browser-facing routes (HTML, UI)
+
+For interactive browser routes where users should be redirected to sign in:
+
+```nginx
+location / {
+  auth_request /oauth2/auth;
+  error_page 401 = @oauth2_signin;
+  proxy_pass http://backend/;
+}
+
+location @oauth2_signin {
+  return 302 /oauth2/sign_in?rd=$scheme://$host$request_uri;
+}
+```
+
+#### API / Machine routes (no redirect)
+
+For API endpoints where clients expect a 401/403 status code (not a redirect):
+
+```nginx
+location /api/ {
+  auth_request /oauth2/auth;
+  error_page 401 =401;  # Pass through the 401 status
+  proxy_pass http://backend/;
+}
+```
+
+This ensures:
+- ✅ Browsers get a redirect and smooth login flow
+- ✅ API clients fail fast with appropriate HTTP status codes
+- ✅ `/oauth2/auth` remains a pure boolean oracle (2xx/401)
+
 When you use ingress-nginx in Kubernetes, you can configure the same behavior with the following annotations on your Ingress resource:
 
 ```yaml
diff --git a/docs/versioned_docs/version-7.12.x/configuration/integration.md b/docs/versioned_docs/version-7.12.x/configuration/integration.md
index c57cfa6b..a5afeda4 100644
--- a/docs/versioned_docs/version-7.12.x/configuration/integration.md
+++ b/docs/versioned_docs/version-7.12.x/configuration/integration.md
@@ -33,9 +33,15 @@ server {
     proxy_pass_request_body           off;
   }
 
+  # Named location for handling OAuth2 sign-in redirects
+  # This ensures the browser receives a proper 302 redirect that it will follow
+  location @oauth2_signin {
+    return 302 /oauth2/sign_in?rd=$scheme://$host$request_uri;
+  }
+
   location / {
     auth_request /oauth2/auth;
-    error_page 401 =403 /oauth2/sign_in;
+    error_page 401 = @oauth2_signin;
 
     # pass information via X-User and X-Email headers to backend,
     # requires running with --set-xauthrequest flag
@@ -77,6 +83,68 @@ server {
 }
 ```
 
+### Understanding the `error_page` redirect pattern
+
+The `auth_request` directive expects the authentication endpoint (`/oauth2/auth`) to return:
+- **2xx**: Request is authenticated, allow access
+- **401 or 403**: Request is not authenticated, deny access
+
+When a 401 is returned, nginx triggers the `error_page` directive. The recommended pattern uses a **named location** (`@oauth2_signin`) that returns a proper **302 redirect**:
+
+
+```nginx
+error_page 401 = @oauth2_signin;
+
+location @oauth2_signin {
+  return 302 /oauth2/sign_in?rd=$scheme://$host$request_uri;
+}
+```
+
+:::warning Avoid `error_page 401 =403` with sign_in
+Some older configurations use `error_page 401 =403 /oauth2/sign_in`. While this works for displaying the sign-in page, it returns a **403 status code** with a `Location` header. Browsers do not automatically follow redirects on 403 responses, which can cause issues when using `--skip-provider-button=true` (users see a "Found." link instead of being automatically redirected).
+
+The named location pattern above ensures the browser receives a standard **302 redirect** that works correctly with all oauth2-proxy configurations.
+:::
+
+### Browser vs API Routes
+
+:::important When to use redirects
+Redirecting authentication failures (302 to `/oauth2/sign_in`) should **only be used for browser-facing routes**. API or machine clients should receive a plain 401/403 response without redirect.
+:::
+
+#### Browser-facing routes (HTML, UI)
+
+For interactive browser routes where users should be redirected to sign in:
+
+```nginx
+location / {
+  auth_request /oauth2/auth;
+  error_page 401 = @oauth2_signin;
+  proxy_pass http://backend/;
+}
+
+location @oauth2_signin {
+  return 302 /oauth2/sign_in?rd=$scheme://$host$request_uri;
+}
+```
+
+#### API / Machine routes (no redirect)
+
+For API endpoints where clients expect a 401/403 status code (not a redirect):
+
+```nginx
+location /api/ {
+  auth_request /oauth2/auth;
+  error_page 401 =401;  # Pass through the 401 status
+  proxy_pass http://backend/;
+}
+```
+
+This ensures:
+- ✅ Browsers get a redirect and smooth login flow
+- ✅ API clients fail fast with appropriate HTTP status codes
+- ✅ `/oauth2/auth` remains a pure boolean oracle (2xx/401)
+
 When you use ingress-nginx in Kubernetes, you can configure the same behavior with the following annotations on your Ingress resource:
 
 ```yaml
diff --git a/docs/versioned_docs/version-7.13.x/configuration/integrations/nginx.md b/docs/versioned_docs/version-7.13.x/configuration/integrations/nginx.md
index a36ed762..ca6402a9 100644
--- a/docs/versioned_docs/version-7.13.x/configuration/integrations/nginx.md
+++ b/docs/versioned_docs/version-7.13.x/configuration/integrations/nginx.md
@@ -43,7 +43,7 @@ server {
 
   location / {
     auth_request /oauth2/auth;
-    error_page 401 =403 /oauth2/sign_in;
+    error_page 401 = @oauth2_signin;
 
     # pass information via X-User and X-Email headers to backend,
     # requires running with --set-xauthrequest flag
@@ -82,9 +82,76 @@ server {
     proxy_pass http://backend/;
     # or "root /path/to/site;" or "fastcgi_pass ..." etc
   }
+
+  # Named location for handling OAuth2 sign-in redirects
+  # This ensures the browser receives a proper 302 redirect that it will follow
+  location @oauth2_signin {
+    return 302 /oauth2/sign_in?rd=$scheme://$host$request_uri;
+  }
 }
 ```
 
+### Understanding the `error_page` redirect pattern
+
+The `auth_request` directive expects the authentication endpoint (`/oauth2/auth`) to return:
+- **2xx**: Request is authenticated, allow access
+- **401 or 403**: Request is not authenticated, deny access
+
+When a 401 is returned, nginx triggers the `error_page` directive. The recommended pattern uses a **named location** (`@oauth2_signin`) that returns a proper **302 redirect**:
+
+```nginx
+error_page 401 = @oauth2_signin;
+
+location @oauth2_signin {
+  return 302 /oauth2/sign_in?rd=$scheme://$host$request_uri;
+}
+```
+
+:::warning Avoid `error_page 401 =403` with sign_in
+Some older configurations use `error_page 401 =403 /oauth2/sign_in`. While this works for displaying the sign-in page, it returns a **403 status code** with a `Location` header. Browsers do not automatically follow redirects on 403 responses, which can cause issues when using `--skip-provider-button=true` (users see a "Found." link instead of being automatically redirected).
+
+The named location pattern above ensures the browser receives a standard **302 redirect** that works correctly with all oauth2-proxy configurations.
+:::
+
+### Browser vs API Routes
+
+:::important When to use redirects
+Redirecting authentication failures (302 to `/oauth2/sign_in`) should **only be used for browser-facing routes**. API or machine clients should receive a plain 401/403 response without redirect.
+:::
+
+#### Browser-facing routes (HTML, UI)
+
+For interactive browser routes where users should be redirected to sign in:
+
+```nginx
+location / {
+  auth_request /oauth2/auth;
+  error_page 401 = @oauth2_signin;
+  proxy_pass http://backend/;
+}
+
+location @oauth2_signin {
+  return 302 /oauth2/sign_in?rd=$scheme://$host$request_uri;
+}
+```
+
+#### API / Machine routes (no redirect)
+
+For API endpoints where clients expect a 401/403 status code (not a redirect):
+
+```nginx
+location /api/ {
+  auth_request /oauth2/auth;
+  error_page 401 =401;  # Pass through the 401 status
+  proxy_pass http://backend/;
+}
+```
+
+This ensures:
+- ✅ Browsers get a redirect and smooth login flow
+- ✅ API clients fail fast with appropriate HTTP status codes
+- ✅ `/oauth2/auth` remains a pure boolean oracle (2xx/401)
+
 When you use ingress-nginx in Kubernetes, you can configure the same behavior with the following annotations on your Ingress resource:
 
 ```yaml
diff --git a/docs/versioned_docs/version-7.14.x/configuration/integrations/nginx.md b/docs/versioned_docs/version-7.14.x/configuration/integrations/nginx.md
index a36ed762..ca6402a9 100644
--- a/docs/versioned_docs/version-7.14.x/configuration/integrations/nginx.md
+++ b/docs/versioned_docs/version-7.14.x/configuration/integrations/nginx.md
@@ -43,7 +43,7 @@ server {
 
   location / {
     auth_request /oauth2/auth;
-    error_page 401 =403 /oauth2/sign_in;
+    error_page 401 = @oauth2_signin;
 
     # pass information via X-User and X-Email headers to backend,
     # requires running with --set-xauthrequest flag
@@ -82,9 +82,76 @@ server {
     proxy_pass http://backend/;
     # or "root /path/to/site;" or "fastcgi_pass ..." etc
   }
+
+  # Named location for handling OAuth2 sign-in redirects
+  # This ensures the browser receives a proper 302 redirect that it will follow
+  location @oauth2_signin {
+    return 302 /oauth2/sign_in?rd=$scheme://$host$request_uri;
+  }
 }
 ```
 
+### Understanding the `error_page` redirect pattern
+
+The `auth_request` directive expects the authentication endpoint (`/oauth2/auth`) to return:
+- **2xx**: Request is authenticated, allow access
+- **401 or 403**: Request is not authenticated, deny access
+
+When a 401 is returned, nginx triggers the `error_page` directive. The recommended pattern uses a **named location** (`@oauth2_signin`) that returns a proper **302 redirect**:
+
+```nginx
+error_page 401 = @oauth2_signin;
+
+location @oauth2_signin {
+  return 302 /oauth2/sign_in?rd=$scheme://$host$request_uri;
+}
+```
+
+:::warning Avoid `error_page 401 =403` with sign_in
+Some older configurations use `error_page 401 =403 /oauth2/sign_in`. While this works for displaying the sign-in page, it returns a **403 status code** with a `Location` header. Browsers do not automatically follow redirects on 403 responses, which can cause issues when using `--skip-provider-button=true` (users see a "Found." link instead of being automatically redirected).
+
+The named location pattern above ensures the browser receives a standard **302 redirect** that works correctly with all oauth2-proxy configurations.
+:::
+
+### Browser vs API Routes
+
+:::important When to use redirects
+Redirecting authentication failures (302 to `/oauth2/sign_in`) should **only be used for browser-facing routes**. API or machine clients should receive a plain 401/403 response without redirect.
+:::
+
+#### Browser-facing routes (HTML, UI)
+
+For interactive browser routes where users should be redirected to sign in:
+
+```nginx
+location / {
+  auth_request /oauth2/auth;
+  error_page 401 = @oauth2_signin;
+  proxy_pass http://backend/;
+}
+
+location @oauth2_signin {
+  return 302 /oauth2/sign_in?rd=$scheme://$host$request_uri;
+}
+```
+
+#### API / Machine routes (no redirect)
+
+For API endpoints where clients expect a 401/403 status code (not a redirect):
+
+```nginx
+location /api/ {
+  auth_request /oauth2/auth;
+  error_page 401 =401;  # Pass through the 401 status
+  proxy_pass http://backend/;
+}
+```
+
+This ensures:
+- ✅ Browsers get a redirect and smooth login flow
+- ✅ API clients fail fast with appropriate HTTP status codes
+- ✅ `/oauth2/auth` remains a pure boolean oracle (2xx/401)
+
 When you use ingress-nginx in Kubernetes, you can configure the same behavior with the following annotations on your Ingress resource:
 
 ```yaml