Merge pull request #212 from d4rken/feat/recent-errors-detail-upstream

feat: add Recent Errors detail panel with provider-aware suggestions

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: tombii

packages/dashboard-web/src/api.ts

@@ -167,7 +167,9 @@ class API extends HttpClient {
 		}
 	}
 
-	async getStats(opts?: { errorsSinceHours?: number }): Promise<Stats> {
+	async getStats(opts?: {
+		errorsSinceHours?: number;
+	}): Promise<StatsWithAccounts> {
 		const startTime = Date.now();
 		const hours = opts?.errorsSinceHours;
 		const url =
@@ -178,7 +180,7 @@ class API extends HttpClient {
 		this.logger.debug(`→ GET ${url}`);
 
 		try {
-			const response = await this.get<Stats>(url);
+			const response = await this.get<StatsWithAccounts>(url);
 			const duration = Date.now() - startTime;
 			this.logger.debug(`← GET ${url} - 200 (${duration}ms)`);
 			return response;

packages/dashboard-web/src/components/OverviewTab.tsx

@@ -31,6 +31,7 @@ export const OverviewTab = React.memo(() => {
 	// Fetch all data using React Query hooks
 	const { data: stats, isLoading: statsLoading } = useStats(
 		REFRESH_INTERVALS.default,
+		24,
 	);
 	const [timeRange, setTimeRange] = useState("24h");
 	const { data: analytics, isLoading: analyticsLoading } = useAnalytics(

packages/dashboard-web/src/components/StatsTab.tsx

@@ -1,5 +1,7 @@
+import type { RecentErrorGroup } from "@better-ccflare/types";
 import { formatPercentage } from "@better-ccflare/ui-common";
-import { RefreshCw } from "lucide-react";
+import { formatDistanceToNow } from "date-fns";
+import { RefreshCw, XCircle } from "lucide-react";
 import { useResetStats, useStats } from "../hooks/queries";
 import { useApiError } from "../hooks/useApiError";
 import { RecentErrorsCard } from "./overview/system-status/RecentErrorsCard";

packages/dashboard-web/src/components/overview/system-status/ErrorDetailsModal.tsx

@@ -17,6 +17,7 @@ import { getErrorMeta } from "./errorCodeMeta";
 
 interface ErrorDetailsModalProps {
 	error: RecentErrorGroup | null;
+	otherAccountsAvailable: boolean;
 	onClose: () => void;
 	onDismiss: (group: RecentErrorGroup) => void;
 }
@@ -54,12 +55,18 @@ function DetailRow({ label, children }: DetailRowProps) {
 
 export function ErrorDetailsModal({
 	error,
+	otherAccountsAvailable,
 	onClose,
 	onDismiss,
 }: ErrorDetailsModalProps) {
 	const open = error !== null;
 
-	const meta = error ? getErrorMeta(error.errorCode) : null;
+	const meta = error
+		? getErrorMeta(error.errorCode, {
+				provider: error.provider,
+				otherAccountsAvailable,
+			})
+		: null;
 	const isWarning = meta?.severity === "warning";
 	const Icon = isWarning ? AlertTriangle : XCircle;
 	const iconColor = isWarning ? "text-warning" : "text-destructive";

packages/dashboard-web/src/components/overview/system-status/RecentErrorRow.tsx

@@ -8,6 +8,7 @@ import { getErrorMeta } from "./errorCodeMeta";
 
 interface RecentErrorRowProps {
 	error: RecentErrorGroup;
+	otherAccountsAvailable: boolean;
 	onClick: () => void;
 	onDismiss: () => void;
 }
@@ -20,10 +21,14 @@ function accountLabel(error: RecentErrorGroup): string {
 
 export function RecentErrorRow({
 	error,
+	otherAccountsAvailable,
 	onClick,
 	onDismiss,
 }: RecentErrorRowProps) {
-	const meta = getErrorMeta(error.errorCode);
+	const meta = getErrorMeta(error.errorCode, {
+		provider: error.provider,
+		otherAccountsAvailable,
+	});
 	const isWarning = meta.severity === "warning";
 	const Icon = isWarning ? AlertTriangle : XCircle;
 	const bgClass = isWarning ? "bg-warning/10" : "bg-destructive/10";

packages/dashboard-web/src/components/overview/system-status/RecentErrorsCard.tsx

@@ -1,6 +1,6 @@
 import { NO_ACCOUNT_ID, type RecentErrorGroup } from "@better-ccflare/types";
 import { useState } from "react";
-import { useStats } from "../../../hooks/queries";
+import { useAccounts, useStats } from "../../../hooks/queries";
 import {
 	Select,
 	SelectContent,
@@ -9,6 +9,7 @@ import {
 	SelectValue,
 } from "../../ui/select";
 import { ErrorDetailsModal } from "./ErrorDetailsModal";
+import { otherAccountsAvailable } from "./otherAccountsAvailable";
 import { RecentErrorRow } from "./RecentErrorRow";
 import { useDismissedErrors } from "./useDismissedErrors";
 import { type ErrorWindowKey, useErrorWindow } from "./useErrorWindow";
@@ -23,6 +24,7 @@ const WINDOW_OPTIONS: Array<{ value: ErrorWindowKey; label: string }> = [
 export function RecentErrorsCard() {
 	const { windowKey, setWindowKey, windowHours } = useErrorWindow();
 	const { data, isLoading } = useStats(undefined, windowHours);
+	const { data: accounts } = useAccounts();
 	const { dismiss, isDismissed } = useDismissedErrors();
 	const [selectedError, setSelectedError] = useState<RecentErrorGroup | null>(
 		null,
@@ -31,6 +33,9 @@ export function RecentErrorsCard() {
 	const recentErrors = data?.recentErrors;
 	const visibleErrors = recentErrors?.filter((err) => !isDismissed(err)) ?? [];
 
+	const hasOtherAvailableAccounts = (errorAccountId: string | null) =>
+		otherAccountsAvailable(accounts, errorAccountId);
+
 	if (isLoading && !data) return null;
 	if (visibleErrors.length === 0) return null;
 
@@ -62,6 +67,7 @@ export function RecentErrorsCard() {
 					<RecentErrorRow
 						key={`${error.accountId ?? NO_ACCOUNT_ID}:${error.errorCode}:${error.latestRequestId}`}
 						error={error}
+						otherAccountsAvailable={hasOtherAvailableAccounts(error.accountId)}
 						onClick={() => setSelectedError(error)}
 						onDismiss={() => dismiss(error)}
 					/>
@@ -70,6 +76,11 @@ export function RecentErrorsCard() {
 
 			<ErrorDetailsModal
 				error={selectedError}
+				otherAccountsAvailable={
+					selectedError
+						? hasOtherAvailableAccounts(selectedError.accountId)
+						: false
+				}
 				onClose={() => setSelectedError(null)}
 				onDismiss={(group) => dismiss(group)}
 			/>

packages/dashboard-web/src/components/overview/system-status/__tests__/errorCodeMeta.test.ts

@@ -0,0 +1,47 @@
+import { describe, expect, test } from "bun:test";
+import { getErrorMeta } from "../errorCodeMeta";
+
+describe("getErrorMeta", () => {
+	test("unknown code returns fallback meta with the code as title", () => {
+		const meta = getErrorMeta("totally_unknown_code");
+		expect(meta.title).toBe("totally_unknown_code");
+		expect(meta.severity).toBe("error");
+	});
+
+	test("model_fallback_429 with no context defaults to a warning that points at Model Mappings", () => {
+		const meta = getErrorMeta("model_fallback_429");
+		expect(meta.severity).toBe("warning");
+		expect(meta.suggestion).toContain("Model Mappings");
+	});
+
+	test("model_fallback_429 with anthropic provider replaces the suggestion with the OAuth-friendly copy", () => {
+		const meta = getErrorMeta("model_fallback_429", { provider: "anthropic" });
+		expect(meta.suggestion).toContain("No action needed");
+	});
+
+	test("model_fallback_429 with anthropic provider and no other accounts upgrades severity and prefixes description", () => {
+		const meta = getErrorMeta("model_fallback_429", {
+			provider: "anthropic",
+			otherAccountsAvailable: false,
+		});
+		expect(meta.severity).toBe("error");
+		expect(meta.description.startsWith("No other accounts are available")).toBe(
+			true,
+		);
+	});
+
+	test("model_fallback_429 with multi-model provider keeps default suggestion and warning severity", () => {
+		const meta = getErrorMeta("model_fallback_429", {
+			provider: "zai",
+			otherAccountsAvailable: true,
+		});
+		expect(meta.severity).toBe("warning");
+		expect(meta.suggestion).toContain("Model Mappings");
+	});
+
+	test("upstream_429_with_reset entry stays unchanged", () => {
+		const meta = getErrorMeta("upstream_429_with_reset");
+		expect(meta.title).toBe("Provider rate limit");
+		expect(meta.severity).toBe("warning");
+	});
+});

packages/dashboard-web/src/components/overview/system-status/__tests__/otherAccountsAvailable.test.ts

@@ -0,0 +1,73 @@
+import { describe, expect, test } from "bun:test";
+import { otherAccountsAvailable } from "../otherAccountsAvailable";
+
+type Account = Parameters<typeof otherAccountsAvailable>[0][number];
+
+const baseAccount: Account = {
+	id: "acc-1",
+	paused: false,
+	rateLimitedUntil: null,
+};
+
+describe("otherAccountsAvailable", () => {
+	test("returns true when a healthy other account exists", () => {
+		const accounts: Account[] = [
+			{ ...baseAccount, id: "acc-self" },
+			{ ...baseAccount, id: "acc-other" },
+		];
+		expect(otherAccountsAvailable(accounts, "acc-self")).toBe(true);
+	});
+
+	test("excludes the error's own account", () => {
+		const accounts: Account[] = [{ ...baseAccount, id: "acc-self" }];
+		expect(otherAccountsAvailable(accounts, "acc-self")).toBe(false);
+	});
+
+	test("excludes paused accounts", () => {
+		const accounts: Account[] = [
+			{ ...baseAccount, id: "acc-self" },
+			{ ...baseAccount, id: "acc-paused", paused: true },
+		];
+		expect(otherAccountsAvailable(accounts, "acc-self")).toBe(false);
+	});
+
+	test("excludes accounts whose rateLimitedUntil is in the future", () => {
+		const future = Date.now() + 60_000;
+		const accounts: Account[] = [
+			{ ...baseAccount, id: "acc-self" },
+			{ ...baseAccount, id: "acc-rl", rateLimitedUntil: future },
+		];
+		expect(otherAccountsAvailable(accounts, "acc-self")).toBe(false);
+	});
+
+	test("counts accounts whose rateLimitedUntil has already elapsed", () => {
+		const past = Date.now() - 60_000;
+		const accounts: Account[] = [
+			{ ...baseAccount, id: "acc-self" },
+			{ ...baseAccount, id: "acc-recovered", rateLimitedUntil: past },
+		];
+		expect(otherAccountsAvailable(accounts, "acc-self")).toBe(true);
+	});
+
+	test("treats null rateLimitedUntil as available", () => {
+		const accounts: Account[] = [
+			{ ...baseAccount, id: "acc-self" },
+			{ ...baseAccount, id: "acc-other", rateLimitedUntil: null },
+		];
+		expect(otherAccountsAvailable(accounts, "acc-self")).toBe(true);
+	});
+
+	test("handles undefined accounts list as no available", () => {
+		expect(otherAccountsAvailable(undefined, "acc-self")).toBe(false);
+	});
+
+	test("returns false when only paused and rate-limited accounts exist", () => {
+		const future = Date.now() + 60_000;
+		const accounts: Account[] = [
+			{ ...baseAccount, id: "acc-self" },
+			{ ...baseAccount, id: "acc-paused", paused: true },
+			{ ...baseAccount, id: "acc-rl", rateLimitedUntil: future },
+		];
+		expect(otherAccountsAvailable(accounts, "acc-self")).toBe(false);
+	});
+});

packages/dashboard-web/src/components/overview/system-status/errorCodeMeta.ts

@@ -9,7 +9,15 @@ export interface ErrorMeta {
 	severity: ErrorSeverity;
 }
 
-const KNOWN_ERROR_META: Record<RateLimitReason, ErrorMeta> = {
+export interface ErrorContext {
+	provider?: string | null;
+	otherAccountsAvailable?: boolean;
+}
+
+const KNOWN_ERROR_META: Record<
+	Exclude<RateLimitReason, "model_fallback_429">,
+	ErrorMeta
+> = {
 	upstream_429_with_reset: {
 		title: "Provider rate limit",
 		description: "The upstream provider returned 429 with a known reset time.",
@@ -31,14 +39,6 @@ const KNOWN_ERROR_META: Record<RateLimitReason, ErrorMeta> = {
 		suggestion: "Historical record — no action needed.",
 		severity: "warning",
 	},
-	model_fallback_429: {
-		title: "Rate limited — no fallback models",
-		description:
-			"The account was rate-limited and has no fallback models configured.",
-		suggestion:
-			"Configure model fallbacks for this account to enable automatic retry.",
-		severity: "error",
-	},
 	all_models_exhausted_429: {
 		title: "All fallback models rate-limited",
 		description: "Every fallback model also returned 429.",
@@ -47,9 +47,42 @@ const KNOWN_ERROR_META: Record<RateLimitReason, ErrorMeta> = {
 	},
 };
 
-export function getErrorMeta(code: string): ErrorMeta {
+function getModelFallbackMeta(context?: ErrorContext): ErrorMeta {
+	const provider = context?.provider ?? null;
+	const otherAccountsAvailable = context?.otherAccountsAvailable;
+
+	const isOAuthOnlyProvider = provider === "anthropic" || provider === "codex";
+
+	const suggestion = isOAuthOnlyProvider
+		? "No action needed — Claude/Codex accounts only serve their native models, so the proxy will use the next account until this one recovers."
+		: 'To retry on the same account before failing over, open this account\'s More actions → Model Mappings and add comma-separated alternates (e.g. "primary, fallback-1").';
+
+	const baseDescription =
+		"This account hit a 429 with only one model configured, so the proxy failed over to the next account in priority order.";
+
+	if (otherAccountsAvailable === false) {
+		return {
+			title: "Account rate-limited — no in-account fallback",
+			description: `No other accounts are available — requests will fail until this account recovers. ${baseDescription}`,
+			suggestion,
+			severity: "error",
+		};
+	}
+
+	return {
+		title: "Account rate-limited — no in-account fallback",
+		description: baseDescription,
+		suggestion,
+		severity: "warning",
+	};
+}
+
+export function getErrorMeta(code: string, context?: ErrorContext): ErrorMeta {
+	if (code === "model_fallback_429") {
+		return getModelFallbackMeta(context);
+	}
 	if (code in KNOWN_ERROR_META) {
-		return KNOWN_ERROR_META[code as RateLimitReason];
+		return KNOWN_ERROR_META[code as keyof typeof KNOWN_ERROR_META];
 	}
 	return {
 		title: code || "Unknown error",

packages/dashboard-web/src/components/overview/system-status/otherAccountsAvailable.ts

@@ -0,0 +1,31 @@
+/**
+ * Predicate used by RecentErrorsCard to decide whether failover from the
+ * account that produced an error has any chance of succeeding.
+ *
+ * An "available" account is one that is:
+ *   - not the account that produced the error,
+ *   - not manually paused, and
+ *   - not currently rate-limited (rateLimitedUntil null or in the past).
+ *
+ * Rate-limited accounts must be excluded — otherwise model_fallback_429
+ * displays as "warning" implying failover will succeed when in fact every
+ * candidate is also exhausted.
+ */
+export type AccountForFailoverCheck = {
+	id: string;
+	paused: boolean;
+	rateLimitedUntil: number | null;
+};
+
+export function otherAccountsAvailable(
+	accounts: AccountForFailoverCheck[] | undefined | null,
+	errorAccountId: string | null,
+): boolean {
+	const now = Date.now();
+	return (accounts ?? []).some(
+		(a) =>
+			a.id !== errorAccountId &&
+			!a.paused &&
+			(a.rateLimitedUntil == null || a.rateLimitedUntil <= now),
+	);
+}