Something went wrong.

Please login again.

1. Class      -> jenis kegagalan apa?
2. Stage      -> terjadi di tahap mana?
3. Actor      -> user, browser, IdP, API, policy engine, attacker, operator?
4. Recovery   -> apa langkah aman berikutnya?
5. Severity   -> UX issue, access issue, security signal, incident?
6. Evidence   -> apa yang harus dicatat untuk debugging/audit?

HTTP 401

{
  "error": {
    "code": "session_expired",
    "category": "session",
    "message": "Your session has expired.",
    "recoverability": "reauth_required",
    "severity": "normal",
    "correlationId": "req_01J...",
    "details": {
      "reauthUrl": "/login",
      "returnToAllowed": true
    }
  }
}

type AuthErrorCategory =
  | 'authentication'
  | 'session'
  | 'oauth_callback'
  | 'authorization'
  | 'identity'
  | 'tenant'
  | 'transport'
  | 'dependency'
  | 'security_signal'
  | 'unknown';

type Recoverability =
  | 'retry_safe'
  | 'retry_after_delay'
  | 'reauth_required'
  | 'step_up_required'
  | 'request_access'
  | 'logout_required'
  | 'contact_admin'
  | 'blocked_security'
  | 'not_recoverable_in_ui';

type AuthErrorSeverity =
  | 'info'
  | 'normal'
  | 'warning'
  | 'security_sensitive'
  | 'incident';

type AuthErrorEnvelope = {
  code: string;
  category: AuthErrorCategory;
  message: string;
  recoverability: Recoverability;
  severity: AuthErrorSeverity;
  correlationId?: string;
  details?: Record<string, unknown>;
};

Frontend should not infer security meaning from free-text message.

HTTP status + stable error code + endpoint context + current auth state

function classifyAuthHttpError(response: Response, body?: AuthErrorEnvelope): ClassifiedAuthFailure {
  if (body?.code) {
    return classifyByCode(body);
  }

  if (response.status === 401) {
    return { kind: 'session_unknown', recoverability: 'reauth_required' };
  }

  if (response.status === 403) {
    return { kind: 'authorization_denied', recoverability: 'request_access' };
  }

  if (response.status === 429) {
    return { kind: 'rate_limited', recoverability: 'retry_after_delay' };
  }

  if (response.status >= 500) {
    return { kind: 'dependency_or_server_failure', recoverability: 'retry_after_delay' };
  }

  return { kind: 'unknown', recoverability: 'not_recoverable_in_ui' };
}

Login form error should be helpful without becoming an account enumeration oracle.

No account exists for alice@example.com.

The email or password is incorrect.

Expired = normal lifecycle.
Revoked = explicit invalidation/security/admin/user action.

Your session expired. Please sign in again.

Your session ended. Please sign in again.

authenticating -> handling_callback -> authenticated/loading_permissions/failed

function CallbackError({ error }: { error: AuthErrorEnvelope }) {
  switch (error.code) {
    case 'oauth_state_mismatch':
    case 'oauth_nonce_mismatch':
      return <SecuritySensitiveLoginError />;

    case 'oauth_user_cancelled':
      return <LoginCancelled />;

    case 'oauth_provider_error':
      return <ProviderLoginError correlationId={error.correlationId} />;

    default:
      return <GenericLoginRecovery correlationId={error.correlationId} />;
  }
}

Authorization failure should not clear session.

403 = resource exists but access denied, if product wants explicit access UX.
404 = not found or hidden, if existence itself is sensitive.

profile_incomplete != missing_permission
account_suspended != session_expired
email_unverified != unauthenticated

authenticated -> identity_gate -> loading_permissions -> ready

URL: /tenant/acme/cases/123
Session active tenant: globex
Cached query key: ['case', '123']

const caseQueryKey = ['tenant', tenantId, 'case', caseId] as const;

{
  "error": {
    "code": "tenant_mismatch",
    "category": "tenant",
    "recoverability": "retry_safe",
    "severity": "security_sensitive",
    "correlationId": "req_abc"
  }
}

async function deleteCase(caseId: string) {
  const decision = can('case.delete', { type: 'case', id: caseId });

  if (!decision.allowed) {
    throw new ForbiddenInUiError(decision.reason);
  }

  const response = await api.delete(`/cases/${caseId}`, {
    headers: {
      'X-Permission-Snapshot-Version': permissions.version,
    },
  });

  if (response.status === 409) {
    await reloadPermissions();
    throw new PermissionChangedError();
  }
}

Permission allowed in UI is only a prediction. Server decision is final.

Auth denied by server
vs
Browser could not carry auth material correctly

Login succeeds, redirect returns, /session says 401 because cookie was not stored.

If a dependency required for safe authorization is unavailable, fail closed for protected action.

OAuth state mismatch. Expected xyz but got abc.

We could not complete sign-in safely. Please try again.

Reference: req_abc123

function recoveryFor(error: AuthErrorEnvelope): RecoveryAction {
  switch (error.recoverability) {
    case 'retry_safe':
      return { type: 'retry' };

    case 'retry_after_delay':
      return { type: 'retry_with_backoff' };

    case 'reauth_required':
      return { type: 'redirect_login', returnTo: safeCurrentPath() };

    case 'step_up_required':
      return { type: 'start_step_up' };

    case 'request_access':
      return { type: 'show_request_access' };

    case 'logout_required':
      return { type: 'force_logout' };

    case 'contact_admin':
      return { type: 'show_contact_admin' };

    case 'blocked_security':
      return { type: 'block_with_generic_security_message' };

    case 'not_recoverable_in_ui':
      return { type: 'show_error_boundary' };
  }
}

export function AuthRouteErrorBoundary() {
  const error = useRouteError();
  const classified = classifyRouteError(error);

  switch (classified.kind) {
    case 'unauthenticated':
      return <RedirectToLogin returnTo={classified.returnTo} />;

    case 'session_expired':
      return <SessionExpiredScreen />;

    case 'forbidden':
      return <NoAccessScreen reason={classified.reason} />;

    case 'tenant_mismatch':
      return <TenantRecoveryScreen />;

    case 'dependency_unavailable':
      return <TemporaryUnavailableScreen correlationId={classified.correlationId} />;

    default:
      return <UnexpectedAuthError correlationId={classified.correlationId} />;
  }
}

Route denied -> route error boundary.
Button denied -> render absent/disabled/request-access.
Mutation denied -> mutation error UI + permission refresh.

User clicks Approve Case.
UI predicted allowed.
Server returns 403 action_not_allowed_in_state.

onError(error, variables, context) {
  const authFailure = classifyAuthFailure(error);

  if (authFailure?.code === 'action_not_allowed_in_state') {
    rollback(context);
    queryClient.invalidateQueries({ queryKey: ['case', variables.caseId] });
    queryClient.invalidateQueries({ queryKey: ['permissions'] });
    showActionNoLongerAvailable();
    return;
  }

  if (authFailure?.recoverability === 'step_up_required') {
    startStepUpFlow({ returnToAction: variables });
    return;
  }

  throw error;
}

Cache is an optimization, not an authority.

redirect to login with returnTo

function safeReturnTo(raw: string | null, origin: string): string {
  if (!raw) return '/';

  try {
    const url = new URL(raw, origin);

    if (url.origin !== origin) return '/';
    if (!url.pathname.startsWith('/')) return '/';
    if (url.pathname.startsWith('//')) return '/';

    return `${url.pathname}${url.search}${url.hash}`;
  } catch {
    return '/';
  }
}

{
  "event": "auth_failure_observed",
  "category": "authorization",
  "code": "missing_permission",
  "recoverability": "request_access",
  "surface": "route_loader",
  "routeId": "case-detail",
  "tenantId": "tnt_123",
  "correlationId": "req_abc",
  "authState": "ready"
}

auth.failure.count{category,code,surface}
auth.failure.recovery.count{recoverability}
auth.session.expired.count
auth.session.revoked.count
auth.oauth.callback_failed.count{code}
auth.authorization.denied.count{action,resourceType}
auth.tenant.mismatch.count
auth.security_signal.count{code}
auth.dependency.unavailable.count{dependency}

type ClassifiedAuthFailure = {
  code: string;
  category: AuthErrorCategory;
  recoverability: Recoverability;
  severity: AuthErrorSeverity;
  transition?: AuthEvent;
  cacheAction?: 'none' | 'clear_user' | 'clear_tenant' | 'invalidate_permissions';
  uiSurface: 'inline' | 'modal' | 'route_error' | 'full_page' | 'silent_metric';
};

function classifyAuthFailure(error: unknown): ClassifiedAuthFailure {
  const envelope = parseAuthErrorEnvelope(error);

  if (!envelope) {
    return {
      code: 'unknown_auth_error',
      category: 'unknown',
      recoverability: 'not_recoverable_in_ui',
      severity: 'warning',
      cacheAction: 'none',
      uiSurface: 'route_error',
    };
  }

  switch (envelope.code) {
    case 'session_expired':
      return {
        code: envelope.code,
        category: 'session',
        recoverability: 'reauth_required',
        severity: 'normal',
        transition: { type: 'REFRESH_EXPIRED', expiredAt: Date.now() },
        cacheAction: 'none',
        uiSurface: 'full_page',
      };

    case 'session_revoked':
      return {
        code: envelope.code,
        category: 'session',
        recoverability: 'logout_required',
        severity: 'security_sensitive',
        transition: { type: 'SESSION_REVOKED', reason: 'server_revoked' },
        cacheAction: 'clear_user',
        uiSurface: 'full_page',
      };

    case 'missing_permission':
      return {
        code: envelope.code,
        category: 'authorization',
        recoverability: 'request_access',
        severity: 'normal',
        cacheAction: 'none',
        uiSurface: 'route_error',
      };

    case 'tenant_mismatch':
      return {
        code: envelope.code,
        category: 'tenant',
        recoverability: 'retry_safe',
        severity: 'security_sensitive',
        cacheAction: 'clear_tenant',
        uiSurface: 'full_page',
      };

    case 'permission_snapshot_stale':
      return {
        code: envelope.code,
        category: 'authorization',
        recoverability: 'retry_safe',
        severity: 'normal',
        cacheAction: 'invalidate_permissions',
        uiSurface: 'inline',
      };

    case 'oauth_state_mismatch':
      return {
        code: envelope.code,
        category: 'oauth_callback',
        recoverability: 'blocked_security',
        severity: 'security_sensitive',
        cacheAction: 'clear_user',
        uiSurface: 'full_page',
      };

    default:
      return {
        code: envelope.code,
        category: envelope.category,
        recoverability: envelope.recoverability,
        severity: envelope.severity,
        cacheAction: 'none',
        uiSurface: 'route_error',
      };
  }
}

Every auth failure must either become state, route error, mutation error, or telemetry-only event.

export async function caseLoader({ request, params }: LoaderFunctionArgs) {
  const session = await requireSession(request);

  if (!session) {
    throw jsonAuthError(401, {
      code: 'session_missing',
      category: 'session',
      recoverability: 'reauth_required',
      severity: 'normal',
    });
  }

  const decision = await can(session, 'case.read', {
    type: 'case',
    id: params.caseId!,
  });

  if (!decision.allowed) {
    throw jsonAuthError(decision.hideExistence ? 404 : 403, {
      code: decision.code,
      category: 'authorization',
      recoverability: decision.requestable ? 'request_access' : 'contact_admin',
      severity: 'normal',
    });
  }

  return loadCase(params.caseId!);
}

function CaseRouteBoundary() {
  const error = useRouteError();
  const failure = classifyAuthFailure(error);

  if (failure.code === 'session_missing') {
    return <LoginRedirect />;
  }

  if (failure.category === 'authorization') {
    return <NoAccess resource="case" />;
  }

  return <RouteError correlationId={getCorrelationId(error)} />;
}

function ApproveCaseButton({ caseId }: { caseId: string }) {
  const mutation = useMutation({
    mutationFn: () => approveCase(caseId),
    onError(error) {
      const failure = classifyAuthFailure(error);

      if (failure.code === 'step_up_required') {
        startStepUp({ action: 'case.approve', resourceId: caseId });
        return;
      }

      if (failure.code === 'action_not_allowed_in_state') {
        queryClient.invalidateQueries({ queryKey: ['case', caseId] });
        showToast('This case can no longer be approved.');
        return;
      }

      if (failure.category === 'authorization') {
        queryClient.invalidateQueries({ queryKey: ['permissions'] });
        showNoAccessDialog();
        return;
      }

      throw error;
    },
  });

  return <button onClick={() => mutation.mutate()}>Approve</button>;
}

if (response.status === 401) logout();

401 session_expired -> refresh or re-auth
401 session_revoked -> forced logout
401 cookie_missing -> browser/config recovery
401 token_audience_invalid -> security/config failure

Route-level 403 -> no access page with request/access path when safe.
Component-level denial -> hidden/disabled with reason when useful.
Mutation-level 403 -> rollback + refresh permission/resource.

1. Apa stable error code-nya?
2. Apa category-nya?
3. Apa HTTP status yang sesuai?
4. Apakah frontend boleh retry?
5. Apakah user perlu login ulang?
6. Apakah user bisa request access?
7. Apakah cache harus dibersihkan?
8. Apakah permission harus di-refresh?
9. Apakah session harus dicabut?
10. Apakah event ini perlu audit?
11. Apakah message aman dari enumeration/leak?
12. Apakah correlation ID tersedia?
13. Apakah route/component/mutation punya UI berbeda?
14. Apakah test case sudah ada?
15. Apakah failure ini security signal?

describe('classifyAuthFailure', () => {
  it('classifies session revocation as logout required and cache clearing', () => {
    const failure = classifyAuthFailure(makeError({
      code: 'session_revoked',
      category: 'session',
      recoverability: 'logout_required',
      severity: 'security_sensitive',
    }));

    expect(failure.recoverability).toBe('logout_required');
    expect(failure.cacheAction).toBe('clear_user');
    expect(failure.severity).toBe('security_sensitive');
  });

  it('does not treat forbidden as unauthenticated', () => {
    const failure = classifyAuthFailure(makeError({
      code: 'missing_permission',
      category: 'authorization',
      recoverability: 'request_access',
      severity: 'normal',
    }));

    expect(failure.category).toBe('authorization');
    expect(failure.recoverability).not.toBe('reauth_required');
  });
});

Part 001 -> Auth is not login.
Part 002 -> Authentication, authorization, identity adalah concern berbeda.
Part 003 -> React auth architecture map.
Part 004 -> Frontend bukan enforcement boundary.
Part 005 -> Browser threat model.
Part 006 -> Auth system invariants.
Part 007 -> Auth state machine.
Part 008 -> Auth failure taxonomy.

failure -> classified -> state transition -> recovery -> telemetry -> test