How do you decide between HTTP status 401, 403 and 404 when a caller is refused, and when would you deliberately return 404 for something that exists but the caller may not see?

## The three questions A refused request fails one of three checks: 1. **Who are you?** — no credentials, expired token, bad signature → **401 Unauthorized** (badly named; it means unauthenticated). 2. **May you?** — identity established, permission denied → **403 Forbidden**. 3. **Does it exist / may you know it exists?** → **404 Not Found**. ## 401 details that get missed 401 is formally a *challenge*: the response must include `WWW-Authenticate` telling the client how to authenticate. ``` HTTP/1.1 401 Unauthorized WWW-Authenticate: Bearer realm="api", error="invalid_token", error_description="expired" ``` This matters in practice: SDKs and browsers use it to decide whether to run a refresh flow. An API that answers 401 with no header leaves clients guessing, and one that answers 403 for an expired token breaks automatic refresh entirely — the client concludes the user lacks permission and logs them out. "Expired token → 401, not 403" is the single most common real bug in this area. Do not put fine-grained reasons in the 401 body. "Unknown user" versus "wrong password" on a login endpoint is a user-enumeration oracle; return one generic failure for both. ## 403 details 403 says: authenticated, understood, refused, and repeating with the same identity will not help. Legitimate uses include role checks, disabled accounts, IP allowlists, and quota/plan restrictions. How much to explain is a judgement call. For an internal or partner API, `{"code":"MISSING_SCOPE","required":"orders:write"}` is enormously helpful and leaks nothing an authenticated partner should not know. For a public API where the mere existence of a resource is sensitive, even "you lack access to order 9931" confirms the order exists. ## The 404-instead-of-403 decision The question to ask is: **is existence itself a secret?** - **Yes** — private repositories, other tenants' records, documents shared by link, user accounts by email. Confirming existence enables enumeration, targeted phishing, or competitive intelligence. Answer **404**, identically for "does not exist" and "exists but not yours", and make sure the timing and body are identical too — a fast 404 and a slow 404 is still an oracle. - **No** — an admin-only endpoint everyone knows about, a feature gated by plan tier, a document in a shared workspace where membership is public. Answer **403** and say why; hiding it just makes support tickets. A critical implementation detail: the check must happen *before* the response differs in any observable way. Fetching the resource, then returning 403 on a permission failure and 404 on a miss, is the leak. The correct shape is a single query scoped to the caller (`WHERE id = ? AND tenant_id = ?`) whose empty result is a 404 by construction — that also prevents the accidental data exposure that comes from loading the row first. ## Keeping debuggability Hiding from the attacker should not mean hiding from your on-call engineer. Log the real reason with the identity, resource id and decision, and return a correlation id in the response body or a header. Support can then answer "why did I get a 404" by looking it up, without the API having said anything to the caller. ## Codes that live nearby - **400** — the request itself is malformed; not an authz decision. - **405 Method Not Allowed** — the URL exists but not with that method; must include `Allow`. - **429 Too Many Requests** — throttled, not forbidden. Using 403 for rate limiting confuses clients that would otherwise back off. - **451** — blocked for legal reasons, a deliberate variant of 403. ## Consistency across the platform Mixed behaviour is itself an oracle: if one service returns 403 for a cross-tenant read and another returns 404, an attacker uses the chatty one. The decision belongs in shared middleware or a policy layer, expressed as a rule ("cross-tenant access is always 404") rather than left to each controller.