@djangocfg/api 2.1.567 → 2.1.570

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@djangocfg/api",
-  "version": "2.1.567",
+  "version": "2.1.570",
   "description": "Auto-generated TypeScript API client with React hooks, SWR integration, and Zod validation for Django REST Framework backends",
   "keywords": [
     "django",
@@ -85,7 +85,7 @@
     "zod": "^4.3.6"
   },
   "devDependencies": {
-    "@djangocfg/typescript-config": "^2.1.567",
+    "@djangocfg/typescript-config": "^2.1.570",
     "@testing-library/react": "^16.3.2",
     "@types/node": "^25.9.5",
     "@types/react": "19.2.15",

package/src/auth/__tests__/formatAuthError.test.ts

@@ -1,15 +1,15 @@
 /**
- * formatAuthError tests (auth/utils/errors.ts).
+ * Auth error resolution tests (auth/utils/errors.ts).
  *
  * Turns whatever the auth layer throws (string, Error, DRF `{detail}`, axios-ish
- * nested `response.data.detail`) into a user-facing string, with a stable
- * fallback. The precedence order matters: message > detail > nested detail, and
- * it must never throw on null/odd shapes.
+ * nested `response.data.detail`, an `APIError`-shaped object) into a user-facing
+ * string, with a stable fallback. The precedence order matters: server prose >
+ * status-code copy > fallback, and it must never throw on null/odd shapes.
  */
 
 import { describe, expect, it } from 'vitest';
 
-import { formatAuthError } from '../utils/errors';
+import { AUTH_ERROR_KEYS, formatAuthError, resolveAuthError } from '../utils/errors';
 
 describe('formatAuthError', () => {
   it('returns a plain string as-is', () => {
@@ -39,10 +39,74 @@ describe('formatAuthError', () => {
   });
 
   it('falls back for null / undefined / empty object', () => {
-    const FALLBACK = 'An unexpected error occurred';
+    const FALLBACK = 'Something went wrong';
     expect(formatAuthError(null)).toBe(FALLBACK);
     expect(formatAuthError(undefined)).toBe(FALLBACK);
     expect(formatAuthError({})).toBe(FALLBACK);
     expect(formatAuthError(42)).toBe(FALLBACK);
   });
+
+  it("prefers the caller's fallback when nothing else identifies the failure", () => {
+    expect(formatAuthError({}, 'Failed to send OTP')).toBe('Failed to send OTP');
+  });
+});
+
+/*
+ * The regression this module exists for: a bare `HTTP 404:` under a sign-in
+ * field. `APIError` builds that string itself when the response carries no
+ * message, and `statusText` is empty under HTTP/2 — so it is a status line
+ * wearing a message's clothes, and every extractor used to hand it straight to
+ * the UI.
+ */
+describe('resolveAuthError — transport strings never reach the UI', () => {
+  it('rejects the bare HTTP fallback and explains the status instead', () => {
+    const err = { message: 'HTTP 404: ', statusCode: 404, name: 'APIError' };
+    const { message, key } = resolveAuthError(err);
+
+    expect(message).not.toMatch(/HTTP/);
+    expect(key).toBe(AUTH_ERROR_KEYS.serverUnavailable);
+  });
+
+  it('rejects it even when statusText filled it in', () => {
+    expect(formatAuthError({ message: 'HTTP 500: Internal Server Error', statusCode: 500 }))
+      .not.toMatch(/HTTP/);
+  });
+
+  it("outranks the caller's fallback with status-derived copy", () => {
+    // A 404 reported as "Failed to send the code" blames the code, not the
+    // endpoint that is missing.
+    const { key } = resolveAuthError({ message: 'HTTP 404: ', statusCode: 404 }, 'Failed to send OTP');
+    expect(key).toBe(AUTH_ERROR_KEYS.serverUnavailable);
+  });
+});
+
+describe('resolveAuthError — status codes', () => {
+  it.each([
+    [401, AUTH_ERROR_KEYS.invalidCredentials],
+    [403, AUTH_ERROR_KEYS.invalidCredentials],
+    [404, AUTH_ERROR_KEYS.serverUnavailable],
+    [429, AUTH_ERROR_KEYS.rateLimited],
+    [500, AUTH_ERROR_KEYS.serverUnavailable],
+    [503, AUTH_ERROR_KEYS.serverUnavailable],
+  ])('maps %i to its key', (statusCode, expected) => {
+    expect(resolveAuthError({ statusCode }).key).toBe(expected);
+  });
+
+  it('reads a Response-shaped `status` too', () => {
+    expect(resolveAuthError({ status: 429 }).key).toBe(AUTH_ERROR_KEYS.rateLimited);
+  });
+
+  it('server prose outranks the status code', () => {
+    const err = { response: { detail: 'This code has expired' }, statusCode: 400 };
+    const { message, key } = resolveAuthError(err);
+
+    expect(message).toBe('This code has expired');
+    // No key: the backend already chose the words, in the caller's locale.
+    expect(key).toBeUndefined();
+  });
+
+  it('reads the APIError body spellings the auth endpoints actually use', () => {
+    expect(formatAuthError({ response: { error: 'Too many attempts' } })).toBe('Too many attempts');
+    expect(formatAuthError({ response: { message: 'Account locked' } })).toBe('Account locked');
+  });
 });

package/src/auth/__tests__/logAuthFailure.test.ts

@@ -0,0 +1,89 @@
+import { describe, expect, it, vi } from 'vitest';
+
+import { logAuthFailure } from '../utils/errors';
+
+/**
+ * A mistyped OTP must not page anyone.
+ *
+ * `@djangocfg/devtools` captures `console.error` as an ERROR event, so every
+ * error-level auth log became a production alert. A customer fat-fingering
+ * their one-time code raised "❌ Error" in Telegram — with consola's `%c` CSS
+ * in the message body, because the capture takes the console string verbatim.
+ * Real faults are unfindable in that.
+ */
+
+const sink = () => ({ warn: vi.fn(), error: vi.fn() });
+
+describe('logAuthFailure', () => {
+  describe('the user got it wrong — warn, no alert', () => {
+    it.each([400, 401, 403, 404, 429, 499])('treats %i as a warning', (statusCode) => {
+      const log = sink();
+      logAuthFailure(log, 'Verify OTP failed:', { statusCode });
+      expect(log.warn).toHaveBeenCalledOnce();
+      expect(log.error).not.toHaveBeenCalled();
+    });
+
+    it('reads `status` too, for a rejection that skipped the interceptor', () => {
+      const log = sink();
+      logAuthFailure(log, 'Verify OTP failed:', { status: 401 });
+      expect(log.warn).toHaveBeenCalledOnce();
+      expect(log.error).not.toHaveBeenCalled();
+    });
+
+    it('passes the message and the error through unchanged', () => {
+      const log = sink();
+      const error = { statusCode: 401 };
+      logAuthFailure(log, 'Verify OTP failed:', error);
+      expect(log.warn).toHaveBeenCalledWith('Verify OTP failed:', error);
+    });
+  });
+
+  describe('something is actually broken — error, raise the alert', () => {
+    it.each([500, 502, 503, 504])('treats %i as an error', (statusCode) => {
+      const log = sink();
+      logAuthFailure(log, 'Verify OTP failed:', { statusCode });
+      expect(log.error).toHaveBeenCalledOnce();
+      expect(log.warn).not.toHaveBeenCalled();
+    });
+
+    it('keeps a network failure at error — it carries no status at all', () => {
+      const log = sink();
+      logAuthFailure(log, 'Verify OTP failed:', new TypeError('Failed to fetch'));
+      expect(log.error).toHaveBeenCalledOnce();
+      expect(log.warn).not.toHaveBeenCalled();
+    });
+
+    it.each([null, undefined, 'a string', 42, { statusCode: 'nonsense' }])(
+      'keeps an unreadable error (%s) at error rather than silencing it',
+      (error) => {
+        const log = sink();
+        logAuthFailure(log, 'Verify OTP failed:', error);
+        expect(log.error).toHaveBeenCalledOnce();
+        expect(log.warn).not.toHaveBeenCalled();
+      },
+    );
+  });
+
+  describe('the boundaries', () => {
+    it('399 is not a client error', () => {
+      const log = sink();
+      logAuthFailure(log, 'x', { statusCode: 399 });
+      expect(log.error).toHaveBeenCalledOnce();
+    });
+
+    it('500 is not a client error', () => {
+      const log = sink();
+      logAuthFailure(log, 'x', { statusCode: 500 });
+      expect(log.error).toHaveBeenCalledOnce();
+    });
+
+    it('prefers statusCode when both fields disagree', () => {
+      /* `statusCode` is the field APIError declares; `status` is the fallback
+         for a foreign shape, so it must not override the real one. */
+      const log = sink();
+      logAuthFailure(log, 'x', { statusCode: 401, status: 500 });
+      expect(log.warn).toHaveBeenCalledOnce();
+      expect(log.error).not.toHaveBeenCalled();
+    });
+  });
+});

package/src/auth/context/AuthContext.tsx

@@ -35,6 +35,7 @@ import { useCfgRouter, useLocalStorage, useQueryParams, useSession } from '../ho
 import { clearProfileCache } from '../hooks/useProfileCache';
 import { useAuthRedirectManager } from '../hooks/useAuthRedirect';
 import { Analytics, AnalyticsCategory, AnalyticsEvent } from '../utils/analytics';
+import { formatAuthError, logAuthFailure } from '../utils/errors';
 import { isDev, isBrowser } from '../utils/env';
 import { authLogger } from '../utils/logger';
 import { AccountsProvider, useAccountsContext } from './AccountsContext';
@@ -71,14 +72,6 @@ const EMAIL_STORAGE_KEY = 'auth_email';
 
 const AuthContext = createContext<AuthContextType | undefined>(undefined);
 
-/** Extract a user-facing message from an APIError response body. */
-const apiErrorMessage = (error: APIError): string => {
-  const body = error.response as
-    | { error?: string; detail?: string; message?: string }
-    | undefined;
-  return body?.error || body?.detail || body?.message || error.errorMessage;
-};
-
 const AuthProviderInternal: React.FC<AuthProviderProps> = ({ children, config }) => {
   const accounts = useAccountsContext();
   const session = useSession();
@@ -266,7 +259,7 @@ const AuthProviderInternal: React.FC<AuthProviderProps> = ({ children, config })
           webmail: result.webmail ?? null,
         };
       } catch (error) {
-        authLogger.error('Request OTP error:', error);
+        logAuthFailure(authLogger, 'Request OTP failed:', error);
 
         if (error instanceof APIError) {
           const body = error.response as
@@ -276,11 +269,11 @@ const AuthProviderInternal: React.FC<AuthProviderProps> = ({ children, config })
           return {
             success: false,
             statusCode: error.statusCode,
-            message: apiErrorMessage(error),
+            message: formatAuthError(error),
             retryAfter: typeof retryAfter === 'number' ? retryAfter : undefined,
           };
         }
-        return { success: false, message: 'Failed to send OTP' };
+        return { success: false, message: formatAuthError(error, 'Failed to send OTP') };
       }
     },
     [],
@@ -359,15 +352,15 @@ const AuthProviderInternal: React.FC<AuthProviderProps> = ({ children, config })
           should_prompt_2fa: result.should_prompt_2fa,
         };
       } catch (error) {
-        authLogger.error('Verify OTP error:', error);
+        logAuthFailure(authLogger, 'Verify OTP failed:', error);
         Analytics.event(AnalyticsEvent.AUTH_OTP_VERIFY_FAIL, {
           category: AnalyticsCategory.AUTH,
           label: 'email',
         });
         if (error instanceof APIError) {
-          return { success: false, message: apiErrorMessage(error) };
+          return { success: false, message: formatAuthError(error) };
         }
-        return { success: false, message: 'Failed to verify OTP' };
+        return { success: false, message: formatAuthError(error, 'Failed to verify OTP') };
       }
     },
     [setStoredEmail, redirectManager, router],
@@ -440,7 +433,7 @@ const AuthProviderInternal: React.FC<AuthProviderProps> = ({ children, config })
           should_prompt_2fa: result.should_prompt_2fa,
         };
       } catch (error) {
-        authLogger.error('Password login error:', error);
+        logAuthFailure(authLogger, 'Password login failed:', error);
         Analytics.event(AnalyticsEvent.AUTH_PASSWORD_LOGIN_FAIL, {
           category: AnalyticsCategory.AUTH,
           label: 'password',
@@ -454,12 +447,12 @@ const AuthProviderInternal: React.FC<AuthProviderProps> = ({ children, config })
           return {
             success: false,
             statusCode: error.statusCode,
-            message: apiErrorMessage(error),
+            message: formatAuthError(error),
             errorCode: body?.error_code,
             retryAfter: typeof body?.retry_after === 'number' ? body.retry_after : undefined,
           };
         }
-        return { success: false, message: 'Failed to sign in' };
+        return { success: false, message: formatAuthError(error, 'Failed to sign in') };
       }
     },
     [setStoredEmail, redirectManager, router],

package/src/auth/hooks/twoFactor.shared.ts

@@ -9,34 +9,19 @@ import { APIError } from '../../_api/generated/helpers';
  * and 6-digit validation slightly differently — three copies that drifted. This
  * module is the single source for both, so every 2FA verb reports errors and
  * validates codes identically.
+ *
+ * Error extraction itself now lives one level up, in `utils/errors`: this
+ * module's own copy was the second of three spellings of the same chain across
+ * the auth layer, and the one that could not tell a status code from prose.
  */
 
 const TOTP_CODE_LENGTH = 6;
 
-/** A 2FA API error body may carry any of these message-ish fields. */
+/** The one field the shared resolver does not read for us. */
 interface TwoFactorErrorBody {
-  error?: unknown;
-  detail?: unknown;
-  message?: unknown;
   attempts_remaining?: unknown;
 }
 
-/**
- * Extract a human-readable message from a thrown error, unwrapping the
- * APIError response body (error → detail → message) before falling back.
- */
-export function extractTwoFactorError(err: unknown, fallback: string): string {
-  if (err instanceof APIError) {
-    const body = (err.response ?? null) as TwoFactorErrorBody | null;
-    if (typeof body?.error === 'string') return body.error;
-    if (typeof body?.detail === 'string') return body.detail;
-    if (typeof body?.message === 'string') return body.message;
-    return err.errorMessage ?? err.message;
-  }
-  if (err instanceof Error) return err.message;
-  return fallback;
-}
-
 /** Pull `attempts_remaining` off an APIError body, or null if absent. */
 export function extractAttemptsRemaining(err: unknown): number | null {
   if (err instanceof APIError) {

package/src/auth/hooks/useGithubAuth.ts

@@ -6,6 +6,7 @@ import { auth } from '../../_api/generated/helpers/auth';
 import { CfgAccountsOauth } from '../../_api/generated/sdk.gen';
 import type { OAuthTokenResponse } from '../../_api/generated/types.gen';
 import { Analytics, AnalyticsCategory, AnalyticsEvent } from '../utils/analytics';
+import { formatAuthError } from '../utils/errors';
 import { authLogger } from '../utils/logger';
 import { useCfgRouter } from './useCfgRouter';
 
@@ -114,7 +115,7 @@ export const useGithubAuth = (options: UseGithubAuthOptions = {}): UseGithubAuth
       window.location.href = response.authorization_url;
 
     } catch (err) {
-      const errorMessage = err instanceof Error ? err.message : 'Failed to start GitHub authentication';
+      const errorMessage = formatAuthError(err, 'Failed to start GitHub authentication');
       authLogger.error('GitHub OAuth start error:', err);
       setError(errorMessage);
       onError?.(errorMessage);
@@ -219,7 +220,7 @@ export const useGithubAuth = (options: UseGithubAuthOptions = {}): UseGithubAuth
       return;
 
     } catch (err) {
-      const errorMessage = err instanceof Error ? err.message : 'GitHub authentication failed';
+      const errorMessage = formatAuthError(err, 'GitHub authentication failed');
       authLogger.error('GitHub OAuth callback error:', err);
       setError(errorMessage);
       onError?.(errorMessage);

package/src/auth/hooks/useTwoFactorSetup.ts

@@ -4,7 +4,8 @@ import { useCallback, useState } from 'react';
 
 import { CfgTotpSetup } from '../../_api/generated/sdk.gen';
 import { authLogger } from '../utils/logger';
-import { extractTwoFactorError, isValidTotpCode } from './twoFactor.shared';
+import { formatAuthError, logAuthFailure } from '../utils/errors';
+import { isValidTotpCode } from './twoFactor.shared';
 
 export interface TwoFactorSetupData {
   /** Device ID to use for confirmation */
@@ -105,8 +106,8 @@ export const useTwoFactorSetup = (
 
       return data;
     } catch (err) {
-      const errorMessage = extractTwoFactorError(err, 'Failed to start 2FA setup');
-      authLogger.error('2FA setup error:', err);
+      const errorMessage = formatAuthError(err, 'Failed to start 2FA setup');
+      logAuthFailure(authLogger, '2FA setup failed:', err);
       setError(errorMessage);
       setSetupStep('idle');
       onError?.(errorMessage);
@@ -153,8 +154,8 @@ export const useTwoFactorSetup = (
       onComplete?.(codes);
       return codes;
     } catch (err) {
-      const errorMessage = extractTwoFactorError(err, 'Invalid code. Please try again.');
-      authLogger.error('2FA setup confirmation error:', err);
+      const errorMessage = formatAuthError(err, 'Invalid code. Please try again.');
+      logAuthFailure(authLogger, '2FA setup confirmation failed:', err);
       setError(errorMessage);
       setSetupStep('scanning'); // Go back to scanning step
       onError?.(errorMessage);

package/src/auth/hooks/useTwoFactorStatus.ts

@@ -4,7 +4,8 @@ import { useCallback, useState } from 'react';
 
 import { CfgTotp } from '../../_api/generated/sdk.gen';
 import { authLogger } from '../utils/logger';
-import { extractTwoFactorError, isValidTotpCode } from './twoFactor.shared';
+import { formatAuthError, logAuthFailure } from '../utils/errors';
+import { isValidTotpCode } from './twoFactor.shared';
 
 export interface TwoFactorDevice {
   id: string;
@@ -70,8 +71,8 @@ export const useTwoFactorStatus = (): UseTwoFactorStatusReturn => {
 
       authLogger.info('2FA status:', response.has_2fa_enabled ? 'enabled' : 'disabled');
     } catch (err) {
-      const errorMessage = extractTwoFactorError(err, 'Failed to fetch 2FA status');
-      authLogger.error('Failed to fetch 2FA status:', err);
+      const errorMessage = formatAuthError(err, 'Failed to fetch 2FA status');
+      logAuthFailure(authLogger, 'Failed to fetch 2FA status:', err);
       setError(errorMessage);
     } finally {
       setIsLoading(false);
@@ -98,8 +99,8 @@ export const useTwoFactorStatus = (): UseTwoFactorStatusReturn => {
       authLogger.info('2FA disabled successfully');
       return true;
     } catch (err: unknown) {
-      const errorMessage = extractTwoFactorError(err, 'Invalid verification code');
-      authLogger.error('Failed to disable 2FA:', err);
+      const errorMessage = formatAuthError(err, 'Invalid verification code');
+      logAuthFailure(authLogger, 'Failed to disable 2FA:', err);
       setError(errorMessage);
       return false;
     } finally {

package/src/auth/hooks/useTwoFactorVerify.ts

@@ -7,9 +7,10 @@ import { CfgTotpVerify } from '../../_api/generated/sdk.gen';
 import type { TotpVerifyUser, VerifyResponse } from '../../_api/generated/types.gen';
 import { Analytics, AnalyticsCategory, AnalyticsEvent } from '../utils/analytics';
 import { authLogger } from '../utils/logger';
+import { formatAuthError, logAuthFailure } from '../utils/errors';
 import { consumeSavedRedirect } from './useAuthRedirect';
 import { useCfgRouter } from './useCfgRouter';
-import { extractAttemptsRemaining, extractTwoFactorError, isValidTotpCode } from './twoFactor.shared';
+import { extractAttemptsRemaining, isValidTotpCode } from './twoFactor.shared';
 
 export interface UseTwoFactorVerifyOptions {
   /** Callback on successful 2FA verification */
@@ -130,8 +131,8 @@ export const useTwoFactorVerify = (
       handleSuccess(response);
       return true;
     } catch (err) {
-      authLogger.error('2FA TOTP verification error:', err);
-      const errorMessage = extractTwoFactorError(err, 'Invalid verification code');
+      logAuthFailure(authLogger, '2FA TOTP verification failed:', err);
+      const errorMessage = formatAuthError(err, 'Invalid verification code');
       const attempts = extractAttemptsRemaining(err);
       if (attempts !== null) setAttemptsRemaining(attempts);
       setError(errorMessage);
@@ -183,8 +184,8 @@ export const useTwoFactorVerify = (
       handleSuccess(response);
       return true;
     } catch (err) {
-      authLogger.error('2FA backup code verification error:', err);
-      const errorMessage = extractTwoFactorError(err, 'Invalid backup code');
+      logAuthFailure(authLogger, '2FA backup code verification failed:', err);
+      const errorMessage = formatAuthError(err, 'Invalid backup code');
       const attempts = extractAttemptsRemaining(err);
       if (attempts !== null) setAttemptsRemaining(attempts);
       setError(errorMessage);

package/src/auth/utils/errors.ts

@@ -5,29 +5,163 @@ const prop = (value: unknown, key: string): unknown =>
     : undefined;
 
 /**
- * Format authentication error for display.
+ * The transport's own fallback message, e.g. `HTTP 404: ` or `HTTP 500: Boom`.
+ *
+ * `APIError` builds this when the caller supplies no message of its own
+ * (`_api/generated/helpers/errors.ts`), so it is never server prose — it is the
+ * status line restated. Under HTTP/2 `statusText` is empty, which is how a bare
+ * `HTTP 404:` reached a sign-in form and told the user nothing at all.
+ */
+const TRANSPORT_FALLBACK = /^HTTP \d{3}:\s*/;
+
+/**
+ * Translation keys for the copy this module can choose.
+ *
+ * Every one already exists, translated, in all 17 locales of `@djangocfg/i18n`
+ * — `api.errors.*` for transport conditions and `ui.errors.*` for the ones a
+ * person can act on. Nothing is added here: a second key saying "Server is
+ * unavailable" in a namespace of its own would be a second owner of the same
+ * sentence, and the one that loses is whichever the caller did not use.
+ *
+ * A 404 maps to `serverUnavailable`, not to `ui.errors.notFound` ("Not found"):
+ * on a sign-in POST the missing thing is the ENDPOINT, which tells the visitor
+ * nothing about a page and everything about the service being down.
+ */
+export const AUTH_ERROR_KEYS = {
+  invalidCredentials: 'ui.errors.unauthorized',
+  rateLimited: 'api.errors.rateLimited',
+  serverUnavailable: 'api.errors.serverUnavailable',
+  networkError: 'api.errors.networkError',
+  generic: 'ui.errors.generic',
+} as const;
+
+export type AuthErrorKey = (typeof AUTH_ERROR_KEYS)[keyof typeof AUTH_ERROR_KEYS];
+
+/**
+ * English copy for each key, so a caller without a translator still renders a
+ * sentence. The catalogue is authoritative; this is the offline twin.
+ */
+const FALLBACK_COPY: Record<AuthErrorKey, string> = {
+  [AUTH_ERROR_KEYS.invalidCredentials]: 'Please sign in to continue',
+  [AUTH_ERROR_KEYS.rateLimited]: 'Too many requests. Please wait.',
+  [AUTH_ERROR_KEYS.serverUnavailable]: 'Server is unavailable',
+  [AUTH_ERROR_KEYS.networkError]: 'Network error',
+  [AUTH_ERROR_KEYS.generic]: 'Something went wrong',
+};
+
+/** Map a status code to the key whose copy explains it. */
+const keyForStatus = (status: number | undefined): AuthErrorKey => {
+  if (status === undefined) return AUTH_ERROR_KEYS.generic;
+  if (status === 401 || status === 403) return AUTH_ERROR_KEYS.invalidCredentials;
+  // A 404 here is a missing endpoint, not a missing page — see AUTH_ERROR_KEYS.
+  if (status === 404) return AUTH_ERROR_KEYS.serverUnavailable;
+  if (status === 429) return AUTH_ERROR_KEYS.rateLimited;
+  if (status >= 500) return AUTH_ERROR_KEYS.serverUnavailable;
+  return AUTH_ERROR_KEYS.generic;
+};
+
+/** What the auth layer decided to show, and why. */
+export interface AuthErrorCopy {
+  /** Ready-to-render text: server prose, or this module's English fallback. */
+  message: string;
+  /**
+   * Set only when `message` came from `FALLBACK_COPY`. A caller holding a
+   * translator renders `t(key)` instead; server prose carries no key because
+   * the backend already chose the words and the locale.
+   */
+  key?: AuthErrorKey;
+}
+
+/**
+ * Decide what a failed auth call should say.
+ *
+ * Order: text the SERVER wrote, then copy chosen from the status code, then a
+ * generic sentence. Server prose wins because the backend knows the specific
+ * reason ("This code has expired") that a status code cannot express.
  *
  * Each candidate is checked to be a string before it is returned. Under the
  * previous `any` the check was only that the property was truthy, so a DRF
  * field-error object (`{detail: {email: [...]}}`) reached the UI as
  * "[object Object]" — an error message that tells the user nothing.
+ *
+ * `HTTP <code>:` strings are rejected on the way through. They are the
+ * transport restating its own status line, not prose anyone wrote to be read,
+ * and treating them as a message is what put a bare `HTTP 404:` under a
+ * sign-in field. The code itself stays useful — `logAuthFailure` puts it in
+ * the console, where diagnosis belongs.
  */
-export const formatAuthError = (error: unknown): string => {
-  if (typeof error === 'string') {
-    return error;
+export const resolveAuthError = (error: unknown, fallback?: string): AuthErrorCopy => {
+  if (typeof error === 'string' && error && !TRANSPORT_FALLBACK.test(error)) {
+    return { message: error };
   }
 
   const candidates = [
     prop(error, 'message'),
     prop(error, 'detail'),
+    prop(prop(error, 'response'), 'error'),
+    prop(prop(error, 'response'), 'detail'),
+    prop(prop(error, 'response'), 'message'),
     prop(prop(prop(error, 'response'), 'data'), 'detail'),
   ];
 
   for (const candidate of candidates) {
-    if (typeof candidate === 'string' && candidate) {
-      return candidate;
+    if (typeof candidate === 'string' && candidate && !TRANSPORT_FALLBACK.test(candidate)) {
+      return { message: candidate };
     }
   }
 
-  return 'An unexpected error occurred';
+  // Both spellings are read: `statusCode` is what `APIError` declares, while a
+  // Response-shaped rejection reaching here from outside the interceptor
+  // carries `status`.
+  const rawStatus = prop(error, 'statusCode') ?? prop(error, 'status');
+  const status = typeof rawStatus === 'number' ? rawStatus : undefined;
+
+  // A caller's own fallback only applies where the status says nothing; a 404
+  // must not be reported as "Failed to send the code".
+  if (status === undefined && fallback) {
+    return { message: fallback };
+  }
+
+  const key = keyForStatus(status);
+  return { message: FALLBACK_COPY[key], key };
+};
+
+/**
+ * `resolveAuthError` for callers that only want the string.
+ *
+ * Kept because most call sites store a plain `error` string in form state and
+ * have no translator to hand.
+ */
+export const formatAuthError = (error: unknown, fallback?: string): string =>
+  resolveAuthError(error, fallback).message;
+
+/**
+ * Log a failed auth call at the level its cause deserves.
+ *
+ * A 4xx on an auth endpoint is the USER getting it wrong — a mistyped OTP, an
+ * expired code, a bad password. It is the endpoint working. Logged through
+ * `console.error` it became a production alert: `@djangocfg/devtools` captures
+ * `console.error` as an `ERROR` event, so every typo raised "❌ Error" in
+ * Telegram, complete with consola's `%c` CSS in the message body. Real faults
+ * drown in that.
+ *
+ * 5xx, a network failure and a broken response contract stay at `error`:
+ * nobody can fix those by retyping, and they are what the alert is for.
+ *
+ * Both `statusCode` (what `APIError` declares) and `status` are read, because
+ * a Response-shaped rejection can reach here from code that does not go
+ * through the interceptor.
+ */
+export const logAuthFailure = (
+  log: { warn: (...args: unknown[]) => void; error: (...args: unknown[]) => void },
+  message: string,
+  error: unknown,
+): void => {
+  const code = prop(error, 'statusCode') ?? prop(error, 'status');
+  const isClientError = typeof code === 'number' && code >= 400 && code < 500;
+  if (isClientError) {
+    log.warn(message, error);
+    return;
+  }
+  log.error(message, error);
 };

package/src/auth/utils/index.ts

@@ -1,5 +1,12 @@
 export { validateEmail } from './validation';
-export { formatAuthError } from './errors';
+export {
+  formatAuthError,
+  logAuthFailure,
+  resolveAuthError,
+  AUTH_ERROR_KEYS,
+  type AuthErrorCopy,
+  type AuthErrorKey,
+} from './errors';
 export {
   resolveGuardIsLoading,
   shouldRedirectToAuth,