Fix PWA Intermittent 404 Error on HTTP Server Redirects in Email Links

1. The Common Email Action Link Pattern

A standard workflow in web development involves emailing customers personalized links to perform specific actions — such as renewing a membership, completing a payment, verifying an account, or filling out a feedback form. The typical request cycle follows these steps:

1. The user receives an email containing a link with an action token (e.g., https://example.com/process-action?token=XYZ).
2. Clicking the link opens an intermediate landing page script or API endpoint that performs backend verification.
3. After verification, the backend script logs the user in, records analytics in the database, and redirects them to the final destination page (e.g., the account dashboard).

Regardless of whether a backend is built with PHP, Node.js, Java, Python, or .NET, developers commonly write this landing page logic using HTTP server redirect headers:

			// --- Node.js (Express) ---
			app.get('/process-action', async (req, res) => {
				const user = await validateToken(req.query.token);
				if (user) {
					await logUserSession(user);
					return res.redirect(302, '/destination-page/'); // PROBLEMS IN PWAs
				}
				res.status(400).send("Link expired or invalid.");
			});

			// --- PHP ---
			$user = validateToken($_GET['token'] ?? '');
			if ($user) {
				logUserSession($user);
				header("Location: /destination-page/", true, 302); // PROBLEMS IN PWAs
				exit;
			} else {
				showError("Link expired or invalid.");
			}

			// --- Java (Spring Boot) ---
			@GetMapping("/process-action")
			public RedirectView processAction(@RequestParam String token) {
				if (validateToken(token)) {
					logUserSession(token);
					return new RedirectView("/destination-page/"); // PROBLEMS IN PWAs
				}
				throw new ResponseStatusException(HttpStatus.BAD_REQUEST);
			}
			

While this server-side redirect approach works seamlessly on standard web applications, it causes unpredictable behavior on Progressive Web Apps (PWAs). Users clicking the link will intermittently see a 404 error page, a blank screen, or an offline fallback layout — even though the destination URL exists and works fine when entered directly into the address bar.

2. Comparing Web Redirection Methods

Understanding why this error happens requires looking at how different redirect techniques interact with the browser network stack regardless of the backend language:

3. Why HTTP Server Redirects Fail in PWAs

A Progressive Web App uses a background script called a Service Worker that sits directly between the browser and your web server. It intercepts every outgoing network call using a fetch event listener to provide offline support and caching.

This creates three language-independent points of failure that trigger intermittent 404s:

4. The Solution: Decouple Server Processing from Navigation

To solve this issue permanently, you must separate server-side processing from client-side navigation. Instead of issuing a 302 redirect header, allow the landing page script to return a standard HTTP 200 OK status code, then trigger the navigation via client-side JavaScript.

Refactored Solution Code

In your intermediate processing endpoint, replace server-side redirect headers with an HTTP 200 OK response containing a client-side navigation script targeted at _self:

			// --- Node.js (Express) ---
			app.get('/process-action', async (req, res) => {
				const user = await validateToken(req.query.token);
				if (user) {
					await logUserSession(user);

					// Send 200 OK with Client-Side Navigation Script
					return res.send("[scripttag]window.open('/destination-page/', '_self');[/scripttag]");
				}
				res.status(400).send("Link expired or invalid.");
			});

			// --- PHP ---
			$user = validateToken($_GET['token'] ?? '');
			if ($user) {
				logUserSession($user);

				// Send 200 OK with Client-Side Navigation Script
				echo "[scripttag]window.open('/destination-page/', '_self');[/scripttag]";
				exit;
			} else {
				showError("Link expired or invalid.");
			}

			// --- Java (Spring Boot) ---
			@GetMapping("/process-action")
			@ResponseBody
			public String processAction(@RequestParam String token) {
				if (validateToken(token)) {
					logUserSession(token);

					// Send 200 OK with Client-Side Navigation Script
					return "[scripttag]window.open('/destination-page/', '_self');[/scripttag]";
				}
				throw new ResponseStatusException(HttpStatus.BAD_REQUEST);
			}
			

5. Key Takeaways for Developers

• Avoid HTTP server redirect headers (301/302) on email landing pages if your web application utilizes a PWA Service Worker.
• Use window.open(url, '_self') to split backend data processing and browser navigation into clean, distinct execution steps.
• Ensure state persistence: Always verify session data and database updates are committed before client navigation executes.