REAL-WORLD SCENARIOS

Intermittent 401s That Aren't Actually Auth Failures

A 401 is supposed to mean one thing: you're not authorized. But in practice, I've seen teams spend hours rotating credentials, regenerating tokens, and rewriting auth fixtures — only to discover the problem had nothing to do with authentication at all. The 401 was a symptom. The disease was something else entirely: a race condition in token setup, a clock drift between services, a cached header from a previous test, or a load balancer that dropped the Authorization header on every third request.

What makes these failures so expensive is that they're intermittent. They pass locally, fail in CI, pass again on retry, and then fail on a different endpoint two hours later. That pattern makes engineers distrust their own test suite, which is worse than a consistent failure. A consistent failure tells you where to look. An intermittent one just erodes confidence until someone adds @pytest.mark.flaky(reruns=3) and calls it done — which is a band-aid over a wound that keeps reopening.

This article walks through the real causes I've encountered behind intermittent 401s, how to instrument your tests to catch them, and what to fix at the suite level so they stop coming back. None of this requires exotic tooling — just careful logging, a disciplined approach to token lifecycle, and a willingness to treat a 401 as a mystery to solve rather than a credential problem to brute-force.

Build an API Automation Framework With Node.js

Learn Node.js, Cucumber, GitHub Copilot, APIs, CI/CD, and modern automation by building a complete framework.

Learn more

The Four Non-Auth Causes Behind Most Intermittent 401s

Before you touch a single credential, rule out the four causes I see most often. They're ordered roughly by how frequently they appear in the wild.

1. Token expiry during a long test run. Your token is valid when the test starts, but the request fires after the expiry window closes. This is especially common in suites that fetch a token once at session scope and then run for twenty minutes. The fix isn't to shorten token lifetime — it's to refresh proactively. I cover the full pattern in my guide on token expiry failures across test environments, but the short version is: store the expiry timestamp alongside the token and check it before every request, not just at startup.

2. Race conditions in parallel test runs. When two workers both try to set up auth state at the same time — writing to the same shared fixture, hitting the same token endpoint, or both calling a login API that returns a session cookie — one of them can get a stale or overwritten credential. The 401 fires on whichever worker lost the race. If your 401s correlate with running tests in parallel, this is almost certainly what's happening. Parallelizing a Python test suite without introducing this kind of shared-state corruption requires isolating auth fixtures per worker, not per session.

3. Header stripping by infrastructure. Load balancers, API gateways, and reverse proxies occasionally strip or mangle the Authorization header. This is especially common when a proxy is configured to handle auth itself and strips the header before forwarding — sometimes only on certain routes, sometimes only above a certain payload size. If your 401s are intermittent and don't correlate with token age or parallelism, log the full request headers at the point of transmission and compare them against what the server actually received (check access logs or a request inspector endpoint if one exists).

4. Clock skew invalidating JWT signatures. JWTs carry an iat (issued-at) and exp claim. If the server's clock is even a few seconds ahead of the machine generating the token, the server may reject the token as "not yet valid" or as already expired. This is rare in well-maintained environments but shows up reliably in Docker-based CI setups where container clocks drift. The tell is that the failure is consistent on CI but never reproduces locally.

The key diagnostic move is to log the HTTP status code, the token's expiry time, the wall-clock time of the request, and the worker ID (if running in parallel) for every failed request. Four data points. Once you have them, the pattern usually becomes obvious within a handful of failures.

Instrumenting Your Test Suite to Catch the Real Culprit

Logging after the fact is too late. By the time you're staring at a CI failure, the token is gone, the timestamp is stale, and the request context has evaporated. The goal is to capture everything you need at the moment the 401 fires.

Here's the pattern I use in pytest with requests. I wrap the session's send method to intercept every response before it reaches the test:

import time
import logging
import pytest
import requests

logger = logging.getLogger(__name__)

class DiagnosticSession(requests.Session):
    def send(self, request, **kwargs):
        response = super().send(request, **kwargs)
        if response.status_code == 401:
            logger.warning(
                "401 on %s %s | auth_header_present=%s | ts=%s",
                request.method,
                request.url,
                "Authorization" in request.headers,
                time.time(),
            )
        return response

@pytest.fixture(scope="session")
def api_session(token_fixture):
    session = DiagnosticSession()
    session.headers.update({"Authorization": f"Bearer {token_fixture.value}"})
    return session

The auth_header_present flag immediately tells you whether the header was dropped before the request left Python — if it's False, the problem is in your fixture or header setup, not in the network. If it's True and you're still getting 401s, the header is being stripped downstream or the token itself is invalid by the time it arrives.

Add the token's expiry time to that log line:

logger.warning(
    "401 | auth_present=%s | token_expires_at=%s | now=%s | delta_seconds=%s",
    "Authorization" in request.headers,
    token_fixture.expires_at,
    time.time(),
    token_fixture.expires_at - time.time(),
)

A negative delta_seconds means the token was already expired when the request fired. A very small positive value (under 5 seconds) suggests a race condition or clock skew. A large positive value means expiry isn't the issue at all — look at the header stripping or JWT validation path instead.

Once you start collecting this data across failures, patterns surface quickly. The approach I use for organizing API test failures so patterns surface fast applies directly here: tag each failure with its cause hypothesis (expiry, race, header, clock), and count. You'll know which fix to prioritize within a few CI runs.

Fixing the Suite So These 401s Stop Coming Back

Diagnosis is only half the job. Here's how to fix each cause at the suite level, not just patch around it.

Token expiry: refresh proactively, not reactively. Don't wait for a 401 to trigger a token refresh. Build a token wrapper that checks remaining lifetime before every request:

import time
import requests

class ManagedToken:
    REFRESH_BUFFER_SECONDS = 30

    def __init__(self, fetch_fn):
        self._fetch = fetch_fn
        self._token = None
        self._expires_at = 0

    @property
    def value(self):
        if time.time() >= self._expires_at - self.REFRESH_BUFFER_SECONDS:
            self._refresh()
        return self._token

    def _refresh(self):
        data = self._fetch()
        self._token = data["access_token"]
        self._expires_at = time.time() + data["expires_in"]

The 30-second buffer absorbs both clock skew and network latency. The value property means callers never think about expiry — they just ask for the token and get a valid one.

Race conditions: scope fixtures to the worker, not the session. In pytest-xdist, use the worker_id fixture to namespace any shared state. If two workers are both writing to the same token cache file or the same in-memory dict, isolate them:

@pytest.fixture(scope="session")
def token_fixture(worker_id, fetch_token):
    # Each worker gets its own token — no shared write contention
    return ManagedToken(fetch_token)

If you're hitting a rate-limited token endpoint, cache tokens per worker in a temp file keyed by worker_id rather than a single shared cache.

Header stripping: add a canary endpoint to your smoke suite. If you suspect infrastructure is stripping headers, add a test that hits a simple echo endpoint (most API gateways expose one, or you can deploy a trivial one) and asserts that the Authorization header is present in the echoed request. Run it first in your suite. If it fails, everything downstream will fail too — and you'll know immediately that the problem is in the infrastructure, not your code.

Clock skew: sync clocks and widen the JWT leeway. In CI, make sure NTP is running in your containers. For JWT validation on the server side, most libraries support a leeway parameter — even a 10-second leeway eliminates virtually all clock-skew-induced failures without meaningfully weakening security. If you don't control the server, the fix is on your side: generate tokens on the same machine (or container) that validates them, or use a time-sync sidecar.

The broader principle is this: intermittent 401s are infrastructure and lifecycle problems wearing an auth costume. Once you instrument properly and collect a few failures' worth of data, the costume comes off fast. Treat each one as a signal worth understanding rather than noise worth suppressing, and your suite will be more trustworthy for it.