docs(admin): state how the account and two-factor failures are classified

Every other workflow section in this reference says how its failures map onto
exit codes; this one only mentioned the usage error for a prompt it could not
offer. The table fills that in, and two notes cover the parts a script author
would otherwise have to discover.

The lockout is worth spelling out. It arrives as the network code, which
normally means "retry", and it is retryable — but only after the delay the
server reports, because the code comes from `SlowDown`. A script that retries
immediately is simply refused again.

A failed `--output-file` write is also called out as the one case where a
non-zero exit does not mean nothing happened: the server has already issued the
set, so the codes are printed and the exit code reports only that the file was
not written.

Two rows are pinned by tests rather than left to drift: that a lockout is
classified as retryable, and that an absent route is a not-found rather than the
unsupported code an up-to-date server sends when at-rest protection is
unconfigured. The enrollment test that covered the latter was named for a route
that does not exist, which is a different failure; it now says what it checks.

Author: sineld

crates/cli/tests/admin_account.rs

@@ -195,7 +195,9 @@ fn mfa_status_succeeds_against_a_server_that_answers() {
 }
 
 #[test]
-fn mfa_enroll_reports_unsupported_when_the_server_has_no_such_route() {
+fn mfa_enroll_reports_unsupported_when_at_rest_protection_is_missing() {
+    // 501, which the server sends when `RUSTFS_IAM_MASTER_KEY` is unset. Not to
+    // be confused with an absent route, which is a 404 and a different code.
     let config_dir = tempfile::tempdir().expect("create config dir");
     let (endpoint, receiver, handle) = start_admin_response_test_server(
         "501 Not Implemented",
@@ -540,3 +542,65 @@ fn user_mfa_status_reports_auth_error_when_the_server_refuses() {
         .expect("captured admin request");
     handle.join().expect("admin test server finished");
 }
+
+// ---------------------------------------------------------------------------
+// The exit-code table in docs/reference/rc/admin.md
+// ---------------------------------------------------------------------------
+
+/// The reference documents how each failure is classified, and that file is a
+/// protected contract. These pin the two rows a reader is most likely to build
+/// retry logic around, so the table cannot drift away from the code silently.
+#[test]
+fn a_lockout_is_reported_as_retryable_rather_than_a_refusal() {
+    // The server answers `SlowDown` once the attempt limit is reached. That maps
+    // to the network code, which normally means "retry" — the reference says why
+    // it means "retry later" here, and this holds it to that class.
+    let config_dir = tempfile::tempdir().expect("create config dir");
+    let (endpoint, receiver, handle) = start_admin_response_test_server(
+        "503 Service Unavailable",
+        "application/json",
+        r#"{"Code":"SlowDown","Message":"too many attempts; try again in 900 seconds"}"#
+            .to_string(),
+    );
+
+    let output = rc()
+        .args([
+            "--json", "admin", "account", "mfa", "activate", "myalias", "--code", "123456",
+        ])
+        .env("RC_CONFIG_DIR", config_dir.path())
+        .env("RC_HOST_myalias", rc_host_alias(&endpoint))
+        .output()
+        .expect("run rc command");
+
+    assert_eq!(output.status.code(), Some(3), "expected NetworkError");
+    receiver
+        .recv_timeout(Duration::from_secs(5))
+        .expect("captured admin request");
+    handle.join().expect("admin test server finished");
+}
+
+#[test]
+fn an_absent_route_is_reported_as_not_found() {
+    // A server predating these endpoints. Distinct from the 501 an up-to-date
+    // server sends when at-rest protection is unconfigured, which is the row
+    // above it in the table.
+    let config_dir = tempfile::tempdir().expect("create config dir");
+    let (endpoint, receiver, handle) = start_admin_response_test_server(
+        "404 Not Found",
+        "application/json",
+        r#"{"Code":"NoSuchKey","Message":"unknown route"}"#.to_string(),
+    );
+
+    let output = rc()
+        .args(["--json", "admin", "account", "mfa", "status", "myalias"])
+        .env("RC_CONFIG_DIR", config_dir.path())
+        .env("RC_HOST_myalias", rc_host_alias(&endpoint))
+        .output()
+        .expect("run rc command");
+
+    assert_eq!(output.status.code(), Some(5), "expected NotFound");
+    receiver
+        .recv_timeout(Duration::from_secs(5))
+        .expect("captured admin request");
+    handle.join().expect("admin test server finished");
+}

docs/reference/rc/admin.md

@@ -191,6 +191,31 @@ asks for confirmation; `--yes` is required in `--json` mode or when stdin is not
 a terminal. The account is left protected by its password alone until the user
 enrols again.
 
+### Exit codes
+
+Every other workflow in this reference states how its failures are classified, so
+these do too. The account and two-factor commands map the server's answer onto
+the standard codes:
+
+| Condition | Code |
+|---|---|
+| Wrong verification code, recovery code, or password | authentication (4) |
+| Locked out after repeated wrong codes | network (3) |
+| At-rest protection not configured on the server | unsupported (7) |
+| Route absent, on a server predating these endpoints | not found (5) |
+| Recovery-code output path already occupied | conflict (6) |
+| Missing, conflicting, or unprompted flags | usage (2) |
+| Already enabled, not enabled, or no pending enrollment | general (1) |
+
+The lockout deserves a note, because network (3) usually means "retry". It is
+retryable here too, but only after the delay the server reports — the code comes
+from `SlowDown`, which is the S3 vocabulary's closest analogue to a rate limit.
+A script that retries immediately will simply be refused again.
+
+A failed `--output-file` write is the one case where a non-zero exit does not mean
+nothing happened: the server has already issued the set, so the codes are printed
+and the exit code reports only that the file was not written.
+
 ### Root identities
 
 A root identity provisioned from `RUSTFS_ACCESS_KEY` cannot have its password or