Return distinct error codes for deleted and disabled users instead of generic 401 #57877
Description
Context
Several official and third-party clients interpret an HTTP 401 Unauthorized response as a terminal authentication failure and react by removing the local account entirely.
This behavior is reasonable when the user has been explicitly deleted from the server.
However, it becomes dangerous when 401 is returned for other situations, such as:
• temporarily disabled users
• administrative suspension
• policy-based access restrictions / Error on FS / reverse proxy etc.
In these cases, the user still exists on the server and may be re-enabled later, but clients currently have no reliable way to distinguish this from a permanent deletion.
Problem
At the moment, Nextcloud returns 401 Unauthorized for multiple, semantically different situations:
• invalid credentials and other possible errors
• deleted user
• disabled user
From a client perspective, these cases are not equivalent, yet they are indistinguishable at the protocol level.
This leads to destructive client-side behavior:
• local data removal
• account deletion
• loss of cached state
• unnecessary re-onboarding when the user is later re-enabled
Additional motivation: false-positive 401 and debuggability
In practice, some deployments observe intermittent 401 responses without a clear root cause (e.g. reverse proxies, authentication backends, token/session edge cases, clock skew, WebDAV auth challenges).
Because the response does not carry any machine-readable reason, client-side debugging is effectively impossible and can result in destructive false positives (clients interpreting the situation as a terminal account removal).
Proposed improvement
Introduce distinct authentication semantics instead of overloading 401 Unauthorized for all cases.
Keep 401 Unauthorized for:
• invalid credentials
• invalid or expired authentication tokens
Add a machine-readable error reason header:
X-NC-Auth-Error: invalid_credentials
X-NC-Auth-Error: user_disabled
X-NC-Auth-Error: user_deleted
This allows clients to implement appropriate behavior, for example:
• invalid_credentials
→ show error only
• user_disabled
→ show informational message, keep local state intact
• user_deleted
→ trigger account removal and optional Remote Wipe status request
Why this matters
• Prevents accidental local data destruction
• Enables correct client behavior for disabled vs deleted users
• Improves debuggability of authentication failures
• Does not break existing clients (header is additive)
• Allows gradual client-side adoption
Summary
This is not a request for a breaking protocol change, but a proposal to make authentication failures explicit, debuggable, and semantically correct, reducing the risk of destructive client behavior caused by ambiguous 401 responses.