fix(zoo-gateway): surface 401/402/403 errors with actionable toasts

Clear the cached token on 401 and offer sign-in. On insufficient credits
or budget limits, open the credits page. On account frozen/banned, open
support. Errors still propagate to the task layer after the toast.

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: James Mtendamema

src/api/providers/zoo-gateway.ts

@@ -1,3 +1,4 @@
+import * as vscode from "vscode"
 import { Anthropic } from "@anthropic-ai/sdk"
 import OpenAI from "openai"
 
@@ -9,8 +10,9 @@ import {
 } from "@roo-code/types"
 
 import { ApiHandlerOptions } from "../../shared/api"
-import { getCachedZooCodeToken, getZooCodeBaseUrl } from "../../services/zoo-code-auth"
+import { clearZooCodeToken, getCachedZooCodeToken, getZooCodeBaseUrl } from "../../services/zoo-code-auth"
 import { Package } from "../../shared/package"
+import { t } from "../../i18n"
 
 import { ApiStream } from "../transform/stream"
 import { convertToOpenAiMessages } from "../transform/openai-format"
@@ -19,6 +21,74 @@ import { addCacheBreakpoints } from "../transform/caching/vercel-ai-gateway"
 import type { SingleCompletionHandler, ApiHandlerCreateMessageMetadata } from "../index"
 import { RouterProvider } from "./router-provider"
 
+function getApiErrorStatus(error: unknown): number | undefined {
+	if (typeof error === "object" && error !== null && "status" in error) {
+		const status = (error as { status: unknown }).status
+		if (typeof status === "number") return status
+	}
+	return undefined
+}
+
+function getApiErrorCode(error: unknown): string | undefined {
+	const err = error as { code?: unknown; error?: { code?: unknown } } | null
+	if (!err) return undefined
+	if (typeof err.code === "string") return err.code
+	if (typeof err.error?.code === "string") return err.error.code
+	return undefined
+}
+
+function buildZooCodeSignInUrl(): string {
+	const callbackUri = encodeURIComponent(
+		`${vscode.env.uriScheme}://${Package.publisher}.${Package.name}/auth-callback`,
+	)
+	const device = encodeURIComponent(vscode.env.appName || "VS Code")
+	const editor = encodeURIComponent("VS Code")
+	return `${getZooCodeBaseUrl()}/dashboard/connect?device=${device}&editor=${editor}&version=${Package.version}&callback_uri=${callbackUri}`
+}
+
+// Caller must always rethrow — this only surfaces UX, never swallows.
+async function surfaceGatewayApiError(error: unknown): Promise<void> {
+	const status = getApiErrorStatus(error)
+	if (status === undefined) return
+	const code = getApiErrorCode(error)
+
+	if (status === 401) {
+		// Wipe before sign-in so the callback rebinds against an empty slot.
+		await clearZooCodeToken()
+		const action = await vscode.window.showErrorMessage(
+			t("common:zooAuth.errors.session_expired"),
+			t("common:zooAuth.buttons.sign_in"),
+		)
+		if (action) {
+			void vscode.env.openExternal(vscode.Uri.parse(buildZooCodeSignInUrl()))
+		}
+		return
+	}
+
+	const isBudgetExceeded = status === 429 && (code === "monthly_budget_exceeded" || code === "daily_budget_exceeded")
+	if (status === 402 || isBudgetExceeded) {
+		const message = isBudgetExceeded
+			? t("common:zooAuth.errors.budget_exceeded")
+			: t("common:zooAuth.errors.out_of_credits")
+		const action = await vscode.window.showErrorMessage(message, t("common:zooAuth.buttons.add_credits"))
+		if (action) {
+			void vscode.env.openExternal(vscode.Uri.parse(`${getZooCodeBaseUrl()}/dashboard/credits`))
+		}
+		return
+	}
+
+	if (status === 403) {
+		const action = await vscode.window.showErrorMessage(
+			t("common:zooAuth.errors.account_unavailable"),
+			t("common:zooAuth.buttons.contact_support"),
+		)
+		if (action) {
+			void vscode.env.openExternal(vscode.Uri.parse(`${getZooCodeBaseUrl()}/support`))
+		}
+		return
+	}
+}
+
 // Extend OpenAI's CompletionUsage to include Zoo Gateway specific fields (same as Vercel AI Gateway)
 interface ZooGatewayUsage extends OpenAI.CompletionUsage {
 	cache_creation_input_tokens?: number
@@ -100,43 +170,48 @@ export class ZooGatewayHandler extends RouterProvider implements SingleCompletio
 			parallel_tool_calls: metadata?.parallelToolCalls ?? true,
 		}
 
-		const completion = await this.client.chat.completions.create(body, {
-			headers: requestHeaders,
-		})
+		try {
+			const completion = await this.client.chat.completions.create(body, {
+				headers: requestHeaders,
+			})
 
-		for await (const chunk of completion) {
-			const delta = chunk.choices[0]?.delta
-			if (delta?.content) {
-				yield {
-					type: "text",
-					text: delta.content,
+			for await (const chunk of completion) {
+				const delta = chunk.choices[0]?.delta
+				if (delta?.content) {
+					yield {
+						type: "text",
+						text: delta.content,
+					}
 				}
-			}
 
-			// Emit raw tool call chunks - NativeToolCallParser handles state management
-			if (delta?.tool_calls) {
-				for (const toolCall of delta.tool_calls) {
-					yield {
-						type: "tool_call_partial",
-						index: toolCall.index,
-						id: toolCall.id,
-						name: toolCall.function?.name,
-						arguments: toolCall.function?.arguments,
+				// Emit raw tool call chunks - NativeToolCallParser handles state management
+				if (delta?.tool_calls) {
+					for (const toolCall of delta.tool_calls) {
+						yield {
+							type: "tool_call_partial",
+							index: toolCall.index,
+							id: toolCall.id,
+							name: toolCall.function?.name,
+							arguments: toolCall.function?.arguments,
+						}
 					}
 				}
-			}
 
-			if (chunk.usage) {
-				const usage = chunk.usage as ZooGatewayUsage
-				yield {
-					type: "usage",
-					inputTokens: usage.prompt_tokens || 0,
-					outputTokens: usage.completion_tokens || 0,
-					cacheWriteTokens: usage.cache_creation_input_tokens || undefined,
-					cacheReadTokens: usage.prompt_tokens_details?.cached_tokens || undefined,
-					totalCost: usage.cost ?? 0,
+				if (chunk.usage) {
+					const usage = chunk.usage as ZooGatewayUsage
+					yield {
+						type: "usage",
+						inputTokens: usage.prompt_tokens || 0,
+						outputTokens: usage.completion_tokens || 0,
+						cacheWriteTokens: usage.cache_creation_input_tokens || undefined,
+						cacheReadTokens: usage.prompt_tokens_details?.cached_tokens || undefined,
+						totalCost: usage.cost ?? 0,
+					}
 				}
 			}
+		} catch (error) {
+			void surfaceGatewayApiError(error)
+			throw error
 		}
 	}
 
@@ -159,6 +234,7 @@ export class ZooGatewayHandler extends RouterProvider implements SingleCompletio
 			const response = await this.client.chat.completions.create(requestOptions)
 			return response.choices[0]?.message.content || ""
 		} catch (error) {
+			void surfaceGatewayApiError(error)
 			if (error instanceof Error) {
 				throw new Error(`Zoo Gateway completion error: ${error.message}`)
 			}

src/i18n/locales/en/common.json

@@ -253,11 +253,20 @@
 			"invalid_token_received": "Zoo Code: Invalid authentication token received.",
 			"token_verification_failed": "Zoo Code: Token verification failed.",
 			"invalid_token": "Zoo Code: Invalid token.",
-			"could_not_verify_token": "Zoo Code: Could not verify token."
+			"could_not_verify_token": "Zoo Code: Could not verify token.",
+			"session_expired": "Zoo Code session expired. Please sign in again to continue using Zoo Gateway.",
+			"out_of_credits": "Zoo Gateway: insufficient credits. Add credits to continue.",
+			"account_unavailable": "Zoo Gateway: your account is currently unavailable. Please contact support.",
+			"budget_exceeded": "Zoo Gateway: usage budget reached. Wait for the budget to reset or top up."
 		},
 		"info": {
 			"connected": "Zoo Code: Successfully connected! You can now use Zoo Code as your AI provider.",
 			"disconnected": "Zoo Code: Disconnected successfully."
+		},
+		"buttons": {
+			"sign_in": "Sign In",
+			"add_credits": "Add Credits",
+			"contact_support": "Contact Support"
 		}
 	},
 	"codeActions": {