How to simulate custom HTTP status codes using service worker fetch interception

Mock Server vs. Service Worker: Which One Actually Lets You Simulate That Bizarre 419 Status Code?

You know the drill. Your backend team just told you the payment gateway will return a 419 Authentication Timeout under certain conditions, and they need the frontend to handle it gracefully before next week's deploy. So you fire up your trusty mock server, hunt down the right config file, add a route, restart the server, and... wait. Then you tweak the response body, restart again, and wait some more.

Now picture this instead: you open your browser, register a service worker, intercept the fetch call in about 40 lines of JavaScript, and return that exact 419 status code — no server restart, no config file, no waiting. You refresh the page and your error boundary renders the fallback UI instantly.

That's the difference I want to unpack today. As someone who's spent way too many hours configuring API mock tools for frontend QA workflows, I've been weighing two approaches side by side: the traditional mock server route versus service worker fetch interception. Let's walk through this as a step-by-step tutorial where I compare both at every stage, so you can decide which fits your workflow.

Step 1: Project Setup — 15-Minute Server Spin-Up vs. 2-Minute SW Registration

The Mock Server Route

When you're using a dedicated mock server — whether that's a standalone Node.js Express setup or a commercial API mock tool — the setup ritual is familiar. You install dependencies, define your routes, configure CORS, set the port, and make sure your frontend's environment variable points to localhost:3001 instead of the real API. On a good day, that's about 15 minutes. On a bad day, when CORS bites you or the port conflicts with something else, it's 45 minutes of Stack Overflow scrolling.

The mock server approach shines when you need a persistent, shared environment that an entire team can hit. But for a solo frontend dev who just needs to test one edge-case status code? It's heavyweight.

The Service Worker Route

Here's the contrast. With service worker fetch interception, your setup looks like this:

Here's the contrast. With service worker fetch interception, your setup looks like this:

self.addEventListener('install', (event) => {
  self.skipWaiting();
});

self.addEventListener('activate', (event) => {
  event.waitUntil(self.clients.claim());
});

That's the boilerplate. You drop this into a file called sw.js in your public directory, register it from your main app entry point with navigator.serviceWorker.register('/sw.js'), and you're done. Two minutes, maybe three if you need to look up the exact syntax. No CORS configuration because the service worker runs in the browser. No port conflicts because there's no server. No environment variable swapping because your frontend still talks to the real API endpoint — the service worker just intercepts the request before it leaves the browser.

The trade-off here is clear: mock servers give you a shared, persistent environment that anyone on your team can hit, while service workers give you a local, ephemeral interception layer that lives inside one developer's browser. For simulating a one-off status code during frontend development, the service worker wins on speed. For standing up a permanent QA environment that the entire team depends on, the mock server still holds the crown.

Step 2: Defining the Route and Returning That 419 Status Code

The Mock Server Route

In a typical mock server setup — let's say you're using something like Express or a dedicated API mock tool — you'd define a route handler that explicitly returns the status code you want. It looks something like this:

app.post('/api/payments/process', (req, res) => {
  res.status(419).json({
    error: 'authentication_timeout',
    message: 'Your session has expired. Please reauthenticate.',
    retryAfter: 30
  });
});

Straightforward, readable, and you can test it immediately with curl or Postman. The downside? Every time you want to change the status code — say, you've already tested 419 and now you need to simulate 422 Validation Error, then 409 Conflict, then 503 Service Unavailable — you're editing the route handler, saving the file, and in many setups, restarting the server. If you're using a commercial mock tool with a UI, you might be clicking through menus and waiting for the tool to reload its configuration. It works, but it's friction.

The Service Worker Route

Now here's where service worker fetch interception gets genuinely fun. You add a fetch event listener inside your sw.js file, inspect the incoming request, and construct a custom Response object with whatever status code you want:

self.addEventListener('fetch', (event) => {
  const url = new URL(event.request.url);

  if (url.pathname === '/api/payments/process' && event.request.method === 'POST') {
    event.respondWith(
      new Response(
        JSON.stringify({
          error: 'authentication_timeout',
          message: 'Your session has expired. Please reauthenticate.',
          retryAfter: 30
        }),
        {
          status: 419,
          statusText: 'Authentication Timeout',
          headers: { 'Content-Type': 'application/json' }
        }
      )
    );
  }
});

That's it. The browser never sends the request to the network. Your frontend's fetch call resolves with a response that has status: 419, and your error handling code runs exactly as it would in production. Change the status code to 422? Edit one number, save, refresh the page. The service worker picks up the new file on reload (thanks to skipWaiting() and clients.claim()), and you're testing the next scenario in under five seconds.

One important detail: the Response constructor accepts any integer as the status code, including non-standard ones like 419, 420, or even completely made-up codes like 499. Mock servers can do this too, but some commercial API mock tools restrict you to a dropdown of standard HTTP status codes. With a service worker, you have zero restrictions — you're constructing the response object manually in JavaScript, so the status code can be whatever integer you need.

Step 3: Making It Dynamic — Conditional Status Codes Without Redeploying

The Mock Server Route

When your QA lead says, "I need to test 419 on the first request, then 200 on the second request, to make sure the retry logic works," a mock server can handle this — but it requires state. You'd typically add a counter or a flag in your route handler:

let requestCount = 0;

app.post('/api/payments/process', (req, res) => {
  requestCount++;
  if (requestCount === 1) {
    res.status(419).json({ error: 'authentication_timeout' });
  } else {
    res.status(200).json({ success: true, transactionId: 'txn_12345' });
  }
});

This works, but now you've got mutable state living in your mock server's memory. Reset the server and the counter goes back to zero. Need to test the scenario again? Restart the server. Want a different sequence? Edit the code, restart, test. It's manageable, but it's not what I'd call ergonomic for rapid iteration.

The Service Worker Route

With a service worker, you can store the same counter in IndexedDB or even in a simple global variable inside the worker's scope. But here's a trick I've started using that feels much more natural: drive the mock behavior from your frontend's URL parameters. You append ?mockStatus=419 to your page URL, and the service worker reads it from the client:

self.addEventListener('fetch', (event) => {
  const url = new URL(event.request.url);

  if (url.pathname !== '/api/payments/process') return;

  event.respondWith(
    self.clients.matchAll().then(clients => {
      const client = clients[0];
      const pageUrl = new URL(client.url);
      const mockStatus = parseInt(pageUrl.searchParams.get('mockStatus'), 10);

      if (mockStatus === 419) {
        return new Response(
          JSON.stringify({ error: 'authentication_timeout', message: 'Session expired' }),
          { status: 419, headers: { 'Content-Type': 'application/json' } }
        );
      }

      return new Response(
        JSON.stringify({ success: true, transactionId: 'txn_12345' }),
        { status: 200, headers: { 'Content-Type': 'application/json' } }
      );
    })
  );
});

Now you can toggle between status codes by simply changing the URL parameter in your browser's address bar. Want to test 419? Go to localhost:3000/?mockStatus=419. Want to test 503? Change it to ?mockStatus=503. No file edits, no server restarts, no state management headaches. The service worker reads the parameter from the active client and responds accordingly. This has genuinely changed how I debug frontend error handling — I can cycle through five different status codes in under a minute.

Step 4: Teardown and Cleanup — When the Testing Session Ends

The Mock Server Route

When you're done testing with a mock server, teardown is usually simple: you stop the server process, switch your frontend's environment variable back to the real API, and you're done. The mock server doesn't linger. But if you forget to switch the environment variable, your frontend will keep hitting the mock server, and you'll wonder why your "production fix" isn't working in staging. I've done this more times than I care to admit.

The Service Worker Route

Service workers are peskier. Once registered, a service worker persists across page reloads and browser sessions. If you forget to unregister it, your fetch interception stays active, and your frontend will keep receiving those mocked 419 responses even when you think you're done testing. Here's how to clean up properly:

navigator.serviceWorker.getRegistrations().then(registrations => {
  registrations.forEach(registration => registration.unregister());
});

You can run this in your browser console, or better yet, add a small "mock mode off" button in your app's dev toolbar that calls this function. Some developers go a step further and gate the service worker registration behind a dev-only flag, so it never registers in production builds at all. That's the approach I'd recommend — wrap the navigator.serviceWorker.register() call in a if (import.meta.env.DEV) check (or equivalent for your framework), and you eliminate the risk of a rogue service worker intercepting requests in production.

When to Use Which: A Practical Decision Framework

After working with both approaches across multiple projects, here's how I'd break down the decision:

• Use a mock server when: You need a shared QA environment that multiple team members hit simultaneously. You're running integration tests in CI/CD that need a stable, always-on endpoint. You're mocking complex request flows that involve multiple API calls, webhooks, or server-side state transitions. You need to simulate network latency or throttling at the transport layer.
• Use service worker fetch interception when: You're a solo frontend dev iterating on error handling for specific status codes. You need to test unusual or non-standard status codes that your mock tool doesn't support. You want to toggle between mock scenarios instantly without restarting anything. You're testing browser-specific behavior like offline mode, cache strategies, or service worker lifecycles themselves.
• Use both when: Your team maintains a shared mock server for baseline scenarios, and individual developers use service workers for rapid local iteration on edge cases. This is actually the setup I've converged on — the mock server handles the "happy path" and common error codes that everyone needs, while the service worker handles the weird, one-off status codes that only matter for the specific feature I'm building right now.

Common Gotchas With Service Worker Fetch Interception

Before you go all-in on this approach, there are a few traps I've fallen into that are worth flagging:

Scope matters. A service worker registered at /sw.js controls requests to all pages under /. If your API calls go to a different origin entirely (say, api.payments.example.com), your service worker won't intercept them unless you handle cross-origin requests explicitly. The fetch event does fire for cross-origin requests, but you need to be aware of opaque responses and CORS behavior.

Caching during development. Browsers aggressively cache sw.js itself. When you edit the file and refresh, you might still be running the old version. Use Update on reload in Chrome DevTools (Application > Service Workers) to force the browser to always grab the latest version during development. This will save you from an hour of wondering why your status code change "isn't working."

The fetch event doesn't fire for all requests. Service workers intercept fetch calls, but not XMLHttpRequest in some edge cases, and not requests initiated by plugins or browser extensions. If your app uses a library that falls back to XMLHttpRequest instead of fetch, your interception might silently miss those calls. Modern HTTP clients like axios and ky use fetch under the hood, so this is rarely an issue with current tooling — but it's worth knowing.

The Bottom Line

Both mock servers and service worker fetch interception have their place in a frontend developer's toolkit. Mock servers remain the right choice for shared, persistent, team-wide API simulation — especially when you need complex stateful behavior or CI integration. But for the specific task of simulating custom HTTP status codes during rapid frontend development, service worker fetch interception is hard to beat. The setup is minimal, the iteration loop is nearly instant, and you have complete freedom over status codes, response bodies, and headers without touching a config file or restarting a process.

The next time your backend team drops a 419 status code on you and says the frontend needs to handle it by Friday, skip the mock server ritual. Register a service worker, intercept the fetch, return a Response with status: 419, and watch your error boundary render exactly as it should. You'll have the feature tested before your mock server would have finished booting.