Debugging a 401: finding the actual cause, not just the status code

A 401 is a category, not a diagnosis

"Unauthorized" covers several genuinely different problems that all happen to share one status code: no credentials were sent at all, the credentials that were sent have expired, they're the wrong type (a Basic header where the server wants Bearer), or they're valid but missing a scope the endpoint requires. Treating all of these as one bug — "auth is broken, go check the token logic" — is how you end up rewriting working refresh-token code because the actual problem was a missing scope on one endpoint.

Read www-authenticate before you touch anything

When a server follows the relevant spec (RFC 6750, for Bearer tokens), a 401 response carries a WWW-Authenticate header that names the specific reason: error="invalid_token" for an expired or malformed token, error="insufficient_scope" when the token is valid but doesn't cover what you're asking for, or no error parameter at all when no credentials were presented in the first place. That's the fastest read you'll get, and it costs nothing to check first.

Not every API bothers with this. Plenty of real-world 401s carry a bare WWW-Authenticate: Bearer with no error detail, or nothing more specific than "Unauthorized" in the body. When that's what you're looking at, treat the header as a first check you rule out, not a diagnosis you're owed — the next two steps don't depend on the server being that informative.

Test whether auth is required at all

Before assuming you know which layer is broken, confirm you're debugging the right one. Replay's Remove Authentication quick action strips both the Authorization and Cookie headers in one tap and resends the request. If the response is still a 401, auth genuinely is the problem. If it changes to something else — a 404, a validation error, or a 200 you didn't expect — the original 401 wasn't really about credentials at all, and you've just saved yourself from debugging the wrong system.

Fix the specific cause, then prove it

Once the header (or the Remove Authentication test) points at a specific cause, edit the request directly in Replay — a corrected Authorization value, a refreshed token, whatever the diagnosis calls for — and resend it. Then open Compare between the original failing attempt and the fixed one. Compare will show you what's measured: the header changed, and the status went from 401 to 200. Whether that specific change is what actually explains the fix, versus something else changing at the same time, is the likely explanation Compare hedges rather than states outright — the same Confirmed/Possible discipline that runs through Investigations. A status code changing is a fact. Why it changed is a conclusion, and it's worth keeping those two things visibly separate, especially when you're about to tell a teammate the bug is fixed.