Client Errors

## Two different questions HTTP splits "you cannot have this" into two answers. **Authentication** asks *who are you?*; **authorization** asks *are you allowed?* Status **401** is a negative answer to the first, **403** to the second. The names mislead. 401 is spelled "Unauthorized" but means *unauthenticated*. 403 is "Forbidden" and is the real authorization failure. Reading them as "401 = no identity, 403 = identity insufficient" removes almost all confusion. ## 401 and the mandatory challenge RFC 9110 says a 401 response **MUST** include a `WWW-Authenticate` header field containing at least one challenge applicable to the target resource. A challenge names an authentication scheme and optional parameters: - `WWW-Authenticate: Basic realm="admin"` — browsers respond by popping the native credential dialog. - `WWW-Authenticate: Bearer realm="api", error="invalid_token", error_description="expired"` — the OAuth 2.0 bearer form (RFC 6750), which lets a client distinguish *expired* from *malformed* and decide whether to refresh. A 401 without any challenge is technically non-conformant, and it is also less useful: the client has no machine-readable hint about how to authenticate. Many APIs ship this bug because a framework filter writes a bare 401. Typical 401 triggers: no `Authorization` header at all; expired or revoked access token; bad signature; wrong audience/issuer on a JWT; session cookie unknown to the store. ## 403 and what it means operationally 403 says: request understood, authorization refused, **do not retry as-is**. The typical causes are role/scope failures (a valid token without the `orders:write` scope), object-level checks (a user asking for a record belonging to another tenant), and non-identity policy (geo-block, IP allowlist, suspended account, read-only maintenance mode). RFC 9110 also allows a server to return 403 rather than reveal that it *could* have succeeded with different credentials. An anonymous request to a never-public resource is a judgement call. If the endpoint accepts credentials, 401 with a challenge is friendlier: it tells the client what to do. If credentials could never help — say, the resource is disabled — 403 is honest. ## The refresh-flow trap Almost every SPA and mobile client implements the same interceptor: *on 401, try the refresh token once, replay the request; on 403, surface a "not allowed" error*. If the API returns 403 for an expired token, users get spurious permission errors and forced logouts. Conversely, if the API returns 401 for a genuine permission failure, clients enter refresh loops — refresh succeeds, request fails 401 again, repeat. Getting this pair right is a contract with your own clients, not pedantry. ## When to hide existence instead A 403 confirms the resource exists. For sensitive object IDs (another tenant's invoice, a private repository) that is an information leak — an attacker can enumerate IDs and read existence from the status code. The common hardening is to return **404** for objects the caller may not see, and reserve 403 for cases where existence is already known to the caller. Pick one policy per resource family and apply it consistently; mixing 403 and 404 for the same class of object re-creates the oracle you were trying to close. ## Body and observability Both statuses may carry a body. Use a machine-readable error shape (a stable `code` plus a human `message`); never echo the token or the internal policy rule that failed. On the server side, log which check failed and the subject identifier — the single most common production complaint is "we return 403 and nobody can tell why". Distinguish, in logs and metrics, authentication failures from authorization failures: a spike in 401s usually means a clock skew, key rotation, or expired secret; a spike in 403s usually means a bad role migration or a misconfigured policy.