fix: fix quota error

Author: albegosu

i18n/locales/en.json

@@ -43,6 +43,11 @@
     "errorUnreachable": "Cannot reach the model. Is Ollama running?",
     "errorUnauthorized": "API key invalid or missing. Check your provider configuration.",
     "errorRateLimit": "Rate limit reached. Add your own API key in Settings to remove this limit.",
+    "errorAppRateLimit": "Rate limit reached. Add your own API key in Settings to remove this limit.",
+    "errorAppRateLimitCta": "Go to Settings",
+    "errorProviderQuota": "Model provider limit reached (e.g. Gemini free tier). Wait {seconds} seconds, then try again — or enable billing, switch model, or use another provider.",
+    "errorProviderQuotaNoWait": "Model provider limit reached. Wait about a minute, then try again — or check billing and usage at your provider, or switch model in Settings.",
+    "errorProviderQuotaCta": "Provider usage limits",
     "errorRateLimitCta": "Go to Settings",
     "errorModel": "Model provider error",
     "sources": "sources",
@@ -160,6 +165,8 @@
     "userResetFail": "Could not clear overrides. Try again.",
     "rateLimitBanner": "rate limit reached",
     "rateLimitBannerHint": "Add your own API key below to bypass the shared usage limit. Your key is encrypted at rest and never shared.",
+    "providerQuotaBanner": "model provider quota reached",
+    "providerQuotaBannerHint": "Your API key is active, but the provider (e.g. Gemini free tier) limits requests per minute. Wait and retry, enable billing at Google AI, or switch to another model or provider below.",
     "ownKey": "your key ✓",
     "systemDefault": "system default",
     "privacyTitle": "privacy note",
@@ -297,7 +304,7 @@
         "dashboard": "open dashboard"
       },
       "geminiApiKey": {
-        "helpText": "Used for embeddings with Gemini"
+        "helpText": "Used for embeddings and chat with Gemini. Free tier limits chat requests (e.g. ~20/min for gemini-2.5-flash); enable billing or use SEARCH_HYDE=false to reduce usage."
       },
       "openaiApiKey": {
         "helpText": "Used for OpenAI embeddings/chat"

i18n/locales/es.json

@@ -43,6 +43,11 @@
     "errorUnreachable": "No se puede alcanzar el modelo. ¿Está Ollama en marcha?",
     "errorUnauthorized": "API key inválida o ausente. Revisa la configuración del proveedor.",
     "errorRateLimit": "Límite de peticiones alcanzado. Añade tu propia API key en Ajustes para eliminar este límite.",
+    "errorAppRateLimit": "Límite de peticiones alcanzado. Añade tu propia API key en Ajustes para eliminar este límite.",
+    "errorAppRateLimitCta": "Ir a Ajustes",
+    "errorProviderQuota": "Límite del proveedor alcanzado (p. ej. Gemini gratis). Espera {seconds} segundos e inténtalo de nuevo — o activa facturación, cambia de modelo o de proveedor.",
+    "errorProviderQuotaNoWait": "Límite del proveedor alcanzado. Espera un minuto e inténtalo de nuevo — o revisa facturación y uso en tu proveedor, o cambia de modelo en Ajustes.",
+    "errorProviderQuotaCta": "Límites del proveedor",
     "errorRateLimitCta": "Ir a Ajustes",
     "errorModel": "Error del proveedor del modelo",
     "sources": "fuentes",
@@ -160,6 +165,8 @@
     "userResetFail": "No se pudieron limpiar las sobreescrituras. Inténtalo de nuevo.",
     "rateLimitBanner": "límite de uso alcanzado",
     "rateLimitBannerHint": "Añade tu propia API key para saltarte el límite compartido. Tu clave se cifra en reposo y nunca se comparte.",
+    "providerQuotaBanner": "cuota del proveedor del modelo alcanzada",
+    "providerQuotaBannerHint": "Tu API key está activa, pero el proveedor (p. ej. Gemini gratis) limita peticiones por minuto. Espera y reintenta, activa facturación en Google AI o cambia de modelo o proveedor abajo.",
     "ownKey": "tu clave ✓",
     "systemDefault": "valor del sistema",
     "privacyTitle": "nota de privacidad",
@@ -297,7 +304,7 @@
         "dashboard": "abrir dashboard"
       },
       "geminiApiKey": {
-        "helpText": "Se usa para embeddings con Gemini"
+        "helpText": "Se usa para embeddings y chat con Gemini. El plan gratis limita peticiones de chat (p. ej. ~20/min en gemini-2.5-flash); activa facturación o SEARCH_HYDE=false para reducir uso."
       },
       "openaiApiKey": {
         "helpText": "Se usa para embeddings/chat de OpenAI"

nuxt.config.ts

@@ -83,6 +83,8 @@ export default defineNuxtConfig({
     searchThreshold: Number(process.env.SEARCH_THRESHOLD ?? 0.2),
     searchHybrid: process.env.SEARCH_HYBRID === 'true',
     searchRerank: process.env.SEARCH_RERANK === 'true',
+    searchHyde: process.env.SEARCH_HYDE !== 'false',
+    conversationTitleLlm: process.env.CONVERSATION_TITLE_LLM !== 'false',
     // Step 6 - RAG
     ragTemperature: Number(process.env.RAG_TEMPERATURE ?? 0.3),
     ragCitations: process.env.RAG_CITATIONS !== 'false',

pages/index.vue

@@ -143,11 +143,19 @@
               </div>
               <p class="wz-muted text-xs">{{ chatErrorMessage }}</p>
               <NuxtLink
-                v-if="isRateLimitError"
+                v-if="isAppRateLimitError"
                 to="/settings?reason=ratelimit"
                 class="inline-block text-[11px] wz-accent underline"
                 @click="dismissError"
-              >{{ t('chat.errorRateLimitCta') }} →</NuxtLink>
+              >{{ t('chat.errorAppRateLimitCta') }} →</NuxtLink>
+              <a
+                v-else-if="isProviderQuotaError"
+                href="https://ai.dev/rate-limit"
+                target="_blank"
+                rel="noopener noreferrer"
+                class="inline-block text-[11px] wz-accent underline"
+                @click="dismissError"
+              >{{ t('chat.errorProviderQuotaCta') }} →</a>
             </div>
           </div>
         </div>
@@ -415,6 +423,7 @@ import { marked } from 'marked'
 import type { SearchResult, ConverseSource } from '~/stores/documents'
 import { useSearchParams, type SearchParamsConfig } from '~/composables/useSearchParams'
 import { fetchLlmModels, getPersistedModel, persistModel, type LlmModelsConfig } from '~/composables/useLlmModels'
+import { classifyLlmError } from '~/utils/llm-errors'
 
 interface KbToolOutput {
   context: string
@@ -600,29 +609,43 @@ const isSearching = computed(() => {
 
 const dismissedError = ref<unknown>(null)
 const visibleChatError = computed(() => chat.error && chat.error !== dismissedError.value)
-const isRateLimitError = computed(() => {
+
+const classifiedChatError = computed(() => {
   const err = chat.error
-  return APICallError.isInstance(err) && err.statusCode === 429
+  return err ? classifyLlmError(err) : null
 })
 
+const isAppRateLimitError = computed(() => classifiedChatError.value?.kind === 'app_rate_limit')
+const isProviderQuotaError = computed(() => classifiedChatError.value?.kind === 'provider_quota')
+
 function dismissError() {
   dismissedError.value = chat.error
 }
 
 const chatErrorMessage = computed(() => {
-  const err = chat.error
-  if (!err) return ''
-  if (APICallError.isInstance(err)) {
-    if (err.statusCode === 401) return t('chat.errorUnauthorized')
-    if (err.statusCode === 429) return t('chat.errorRateLimit')
-    if (err.statusCode === 503) return t('chat.errorUnreachable')
-    return `${t('chat.errorModel')} (${err.statusCode}): ${err.message}`
-  }
-  const msg = err instanceof Error ? err.message : String(err)
-  if (msg.includes('fetch failed') || msg.includes('ECONNREFUSED') || msg.includes('503')) {
-    return t('chat.errorUnreachable')
+  const classified = classifiedChatError.value
+  if (!classified) return ''
+
+  switch (classified.kind) {
+    case 'app_rate_limit':
+      return t('chat.errorAppRateLimit')
+    case 'provider_quota':
+      if (classified.retryAfterSeconds != null) {
+        return t('chat.errorProviderQuota', { seconds: classified.retryAfterSeconds })
+      }
+      return t('chat.errorProviderQuotaNoWait')
+    case 'unauthorized':
+      return t('chat.errorUnauthorized')
+    case 'unreachable':
+      return t('chat.errorUnreachable')
+    case 'model':
+      if (APICallError.isInstance(chat.error)) {
+        return `${t('chat.errorModel')} (${chat.error.statusCode}): ${chat.error.message}`
+      }
+      return classified.rawMessage || t('chat.errorGeneric')
+    default:
+      return classified.rawMessage || t('chat.errorGeneric')
   }
-  return msg || t('chat.errorGeneric')
 })
 
 interface DisplayMessage {
@@ -861,6 +884,15 @@ watch(
   },
 )
 
+watch(
+  () => chat.error,
+  (err) => {
+    if (err && classifyLlmError(err).kind === 'provider_quota' && typeof window !== 'undefined') {
+      window.sessionStorage.setItem('rag-ui:providerQuotaAt', String(Date.now()))
+    }
+  },
+)
+
 async function send() {
   const text = input.value.trim()
   if (!text || isBusy.value) return

pages/settings.vue

@@ -10,6 +10,15 @@
       <p class="wz-muted">{{ t('settings.rateLimitBannerHint') }}</p>
     </div>
 
+    <div
+      v-if="showProviderQuotaBanner"
+      class="mb-5 wz-panel p-4 text-xs space-y-1"
+      style="border-color: var(--term-accent);"
+    >
+      <p class="wz-accent font-mono">⚡ {{ t('settings.providerQuotaBanner') }}</p>
+      <p class="wz-muted">{{ t('settings.providerQuotaBannerHint') }}</p>
+    </div>
+
     <div class="mb-6">
       <h1 class="text-lg font-semibold wz-strong">{{ t('settings.userTitle') }}</h1>
       <p class="text-xs wz-faint mt-1">{{ t('settings.userSubtitle') }}</p>
@@ -100,6 +109,7 @@ const { t } = useI18n()
 const route = useRoute()
 
 const showRateLimitBanner = computed(() => route.query.reason === 'ratelimit')
+const showProviderQuotaBanner = computed(() => route.query.reason === 'provider-quota')
 
 const activeTab = ref('apis')
 const saving = ref(false)

server/api/chat.post.ts

@@ -16,6 +16,12 @@ import {
   refreshConversationTitleFromUserPrompt,
 } from '../utils/conversations.service'
 import { scheduleRefineConversationTitle } from '../utils/conversation-title-llm'
+import {
+  classifyLlmError,
+  formatAppRateLimitMessage,
+  formatProviderQuotaMessage,
+} from '../utils/llm-errors'
+import { markProviderQuotaHit } from '../utils/llm-quota-guard'
 
 const MAX_MESSAGES = 50
 const MAX_TEXT_PER_PART = 64 * 1024
@@ -45,18 +51,34 @@ const bodySchema = z.object({
 })
 
 function classifyError(error: unknown): { statusCode: number; message: string } {
-  if (APICallError.isInstance(error)) {
-    const code = error.statusCode ?? 502
-    if (code === 401) return { statusCode: 401, message: 'Model API key is invalid or missing.' }
-    if (code === 429) return { statusCode: 429, message: 'Model rate limit reached. Please wait and try again.' }
-    if (code >= 500) return { statusCode: 502, message: `Model provider returned ${code}. Try again later.` }
-    return { statusCode: code, message: error.message }
-  }
-  const msg = error instanceof Error ? error.message : String(error)
-  if (msg.includes('fetch failed') || msg.includes('ECONNREFUSED') || msg.includes('ENOTFOUND')) {
-    return { statusCode: 503, message: 'Cannot reach the model. Is Ollama running?' }
+  const classified = classifyLlmError(error)
+  switch (classified.kind) {
+    case 'app_rate_limit':
+      return { statusCode: 429, message: formatAppRateLimitMessage() }
+    case 'provider_quota':
+      return {
+        statusCode: 429,
+        message: formatProviderQuotaMessage(classified.retryAfterSeconds),
+      }
+    case 'unauthorized':
+      return { statusCode: 401, message: 'Model API key is invalid or missing.' }
+    case 'unreachable':
+      return { statusCode: 503, message: 'Cannot reach the model. Is Ollama running?' }
+    case 'model':
+      if (APICallError.isInstance(error)) {
+        const code = error.statusCode ?? 502
+        if (code >= 500) {
+          return { statusCode: 502, message: `Model provider returned ${code}. Try again later.` }
+        }
+        return { statusCode: code, message: error.message }
+      }
+      return { statusCode: classified.statusCode, message: classified.rawMessage || 'Model provider error.' }
+    default:
+      return {
+        statusCode: classified.statusCode,
+        message: classified.rawMessage || 'Unexpected model error.',
+      }
   }
-  return { statusCode: 502, message: msg || 'Unexpected model error.' }
 }
 
 function validateMessageSize(messages: UIMessage[]): void {
@@ -165,6 +187,7 @@ export default defineEventHandler(async (event) => {
     // Stream setup failed (e.g. bad API key, unreachable Ollama). The user
     // message has NOT been persisted yet, so there's no orphan to clean up.
     console.error('[chat] pre-stream error:', error)
+    if (classifyLlmError(error).kind === 'provider_quota') markProviderQuotaHit(error)
     const { statusCode, message } = classifyError(error)
     throw createError({ statusCode, statusMessage: message })
   }

server/utils/agent.service.ts

@@ -25,6 +25,8 @@ import {
 import { truncate } from './text'
 import { parseMemoryCommand, getMessageText, type MemoryCommand } from './agent-commands'
 import { sanitizeUIMessagesForAgent } from './agent-messages'
+import { isProviderQuotaError } from './llm-errors'
+import { markProviderQuotaHit } from './llm-quota-guard'
 
 async function getLlmCfg() {
   const config = useRuntimeConfig()
@@ -76,13 +78,14 @@ async function getLlmCfg() {
 
 async function getRagCfg() {
   const config = useRuntimeConfig()
-  const [tempStr, citationsStr, maxCtxStr, langStr, promptStr, maxStepsStr] = await Promise.all([
+  const [tempStr, citationsStr, maxCtxStr, langStr, promptStr, maxStepsStr, searchHydeStr] = await Promise.all([
     getSetting('RAG_TEMPERATURE', String(config.ragTemperature ?? 0.3)),
     getSetting('RAG_CITATIONS', String(config.ragCitations ?? true)),
     getSetting('RAG_MAX_CONTEXT', String(config.ragMaxContext ?? 4096)),
     getSetting('RAG_RESPONSE_LANG', String(config.ragResponseLang ?? 'auto')),
     getSetting('RAG_SYSTEM_PROMPT', String(config.ragSystemPrompt ?? '')),
     getSetting('AGENT_MAX_STEPS', String(config.agentMaxSteps ?? 5)),
+    getSetting('SEARCH_HYDE', String(config.searchHyde ?? true)),
   ])
   return {
     ragTemperature: getNumericSetting(tempStr, 0.3),
@@ -91,6 +94,7 @@ async function getRagCfg() {
     ragResponseLang: langStr || 'auto',
     ragSystemPrompt: promptStr,
     agentMaxSteps: Math.max(1, Math.min(20, getNumericSetting(maxStepsStr, 5))),
+    searchHyde: getBoolSetting(searchHydeStr, true),
   }
 }
 
@@ -166,7 +170,8 @@ function buildKbTools(
       execute: async ({ query }) => {
         const safeQuery = truncate(query.trim(), 512)
         const t0 = Date.now()
-        const { results, sources, context } = await rag(safeQuery, limit, workspaceId, hydeModel)
+        const hyde = hydeModel && ragCfg.searchHyde ? hydeModel : undefined
+        const { results, sources, context } = await rag(safeQuery, limit, workspaceId, hyde)
         const latencyMs = Date.now() - t0
         for (const r of results) bucket.push(r)
         const truncatedContext = truncate(context || '(no matching passages found)', cfg.ragMaxContext)
@@ -243,13 +248,15 @@ export async function agentStreamText(
     model,
     system,
     messages: modelMessages,
+    maxRetries: 0,
     ...(searchMode !== 'direct' && {
       tools: buildKbTools(workspaceId, limit, retrievedChunks, model, cfg),
       stopWhen: stepCountIs(cfg.agentMaxSteps),
       ...(searchMode === 'search' && { toolChoice: 'required' }),
     }),
     temperature: cfg.ragTemperature,
     onError: ({ error }) => {
+      if (isProviderQuotaError(error)) markProviderQuotaHit(error)
       console.error('[agent] streamText error:', error)
     },
   })

server/utils/conversation-title-llm.ts

@@ -2,6 +2,9 @@ import { generateText } from 'ai'
 import { prisma } from './prisma'
 import { stripNul, truncate } from './text'
 import { getLlmModel } from './agent.service'
+import { getSetting, getBoolSetting } from './settings.service.ts'
+import { isProviderQuotaError } from './llm-errors'
+import { markProviderQuotaHit, shouldSuppressOptionalLlmCalls } from './llm-quota-guard'
 
 const TITLE_MAX = 80
 const TRANSCRIPT_MSG_CAP = 16
@@ -21,8 +24,17 @@ export function scheduleRefineConversationTitle(conversationId: string): void {
   void refineConversationTitleFromTranscript(conversationId)
 }
 
+async function isConversationTitleLlmEnabled(): Promise<boolean> {
+  const config = useRuntimeConfig()
+  const raw = await getSetting('CONVERSATION_TITLE_LLM', String(config.conversationTitleLlm ?? true))
+  return getBoolSetting(raw, true)
+}
+
 async function refineConversationTitleFromTranscript(conversationId: string): Promise<void> {
   try {
+    if (!(await isConversationTitleLlmEnabled())) return
+    if (shouldSuppressOptionalLlmCalls()) return
+
     const assistantN = await prisma.message.count({
       where: { conversationId, role: 'assistant' },
     })
@@ -52,6 +64,7 @@ async function refineConversationTitleFromTranscript(conversationId: string): Pr
       prompt: `Transcript:\n---\n${transcript}\n---\nTitle:`,
       maxOutputTokens: 48,
       temperature: 0.2,
+      maxRetries: 0,
     })
 
     const line = stripNul(text ?? '')
@@ -67,7 +80,8 @@ async function refineConversationTitleFromTranscript(conversationId: string): Pr
       where: { id: conversationId },
       data: { title },
     })
-  } catch {
+  } catch (err) {
+    if (isProviderQuotaError(err)) markProviderQuotaHit(err)
     /* optional refinement */
   }
 }

server/utils/llm-errors.ts

@@ -0,0 +1,11 @@
+export {
+  classifyLlmError,
+  errorMessageFromUnknown,
+  formatAppRateLimitMessage,
+  formatProviderQuotaMessage,
+  isAppRateLimitError,
+  isProviderQuotaError,
+  parseRetryAfterSeconds,
+  type ClassifiedLlmError,
+  type LlmErrorKind,
+} from '../../utils/llm-errors'

server/utils/llm-quota-guard.ts

@@ -0,0 +1,16 @@
+import { isProviderQuotaError } from './llm-errors'
+
+/** After a provider quota error, skip optional LLM calls (title refinement, etc.) for this long. */
+const SUPPRESS_MS = 5 * 60_000
+
+let lastProviderQuotaAt = 0
+
+export function markProviderQuotaHit(errorOrMessage?: unknown): void {
+  if (errorOrMessage === undefined || isProviderQuotaError(errorOrMessage)) {
+    lastProviderQuotaAt = Date.now()
+  }
+}
+
+export function shouldSuppressOptionalLlmCalls(): boolean {
+  return Date.now() - lastProviderQuotaAt < SUPPRESS_MS
+}