fix: return clean errors and refund quota on AI provider failures

AI routes had no consistent error handling — a provider failure (e.g.
OpenRouter returning a degraded-model error) crashed the route as an
uncaught 500 and, worse, still charged the user's monthly aiCall
quota for a request that never succeeded.

Adds withAiQuota()/aiErrorResponse() (lib/ai/ai-error.ts) and applies
them across all 12 AI generation routes: charges the quota, runs the
AI call, refunds the credit and returns a clean user-facing message
if it throws. Frontend needs no changes — existing dialogs already
toast whatever `error` string comes back.

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

apps/web/app/api/v1/ai/adapt/[id]/route.ts

@@ -3,7 +3,7 @@ import { z } from "zod";
 import { and, eq } from "@epicure/db";
 import { db, recipes, recipeIngredients, recipeSteps } from "@epicure/db";
 import { requireSession } from "@/lib/api-auth";
-import { checkAndIncrementTierLimit } from "@/lib/tiers";
+import { withAiQuota } from "@/lib/ai/ai-error";
 import { adaptRecipe } from "@/lib/ai/features/adapt-recipe";
 import { withUserKey } from "@/lib/ai/resolve-user-key";
 import { getUserPrivateBio } from "@/lib/ai/user-bio";
@@ -43,27 +43,30 @@ export async function POST(req: NextRequest, { params }: Params) {
     return NextResponse.json({ error: "Provide at least one constraint" }, { status: 400 });
   }
 
-  await checkAndIncrementTierLimit(userId, session!.user.tier as "free" | "pro", "aiCall");
-
   const [aiConfig, privateBio] = await Promise.all([
     withUserKey(userId, { provider: parsed.data.provider, model: parsed.data.model }),
     getUserPrivateBio(userId),
   ]);
-  const adapted = await adaptRecipe(
+
-    {
+  const result = await withAiQuota(userId, session!.user.tier as "free" | "pro", () =>
-      title: recipe.title,
+    adaptRecipe(
-      description: recipe.description,
+      {
-      baseServings: recipe.baseServings,
+        title: recipe.title,
-      ingredients: recipe.ingredients,
+        description: recipe.description,
-      steps: recipe.steps,
+        baseServings: recipe.baseServings,
-    },
+        ingredients: recipe.ingredients,
-    {
+        steps: recipe.steps,
-      excludeIngredients: parsed.data.excludeIngredients,
+      },
-      extraConstraints: parsed.data.extraConstraints,
+      {
-    },
+        excludeIngredients: parsed.data.excludeIngredients,
-    { ...aiConfig, userContext: privateBio ?? undefined },
+        extraConstraints: parsed.data.extraConstraints,
-    (session!.user as { locale?: string }).locale ?? "en"
+      },
+      { ...aiConfig, userContext: privateBio ?? undefined },
+      (session!.user as { locale?: string }).locale ?? "en"
+    )
   );
+  if (!result.ok) return result.response;
+  const adapted = result.data;
 
   const newId = crypto.randomUUID();
   const now = new Date();

apps/web/app/api/v1/ai/drinks/[id]/route.ts

@@ -3,7 +3,7 @@ import { z } from "zod";
 import { and, eq } from "@epicure/db";
 import { db, recipes } from "@epicure/db";
 import { requireSession } from "@/lib/api-auth";
-import { checkAndIncrementTierLimit } from "@/lib/tiers";
+import { withAiQuota } from "@/lib/ai/ai-error";
 import { suggestDrinks } from "@/lib/ai/features/suggest-drinks";
 import { withUserKey } from "@/lib/ai/resolve-user-key";
 import { getUserPrivateBio } from "@/lib/ai/user-bio";
@@ -34,24 +34,26 @@ export async function POST(req: NextRequest, { params }: Params) {
   const parsed = Schema.safeParse(body ?? {});
   if (!parsed.success) return NextResponse.json({ error: "Validation error" }, { status: 400 });
 
-  await checkAndIncrementTierLimit(session!.user.id, session!.user.tier as "free" | "pro", "aiCall");
-
   const [aiConfig, privateBio] = await Promise.all([
     withUserKey(session!.user.id, { provider: parsed.data.provider, model: parsed.data.model }),
     getUserPrivateBio(session!.user.id),
   ]);
-  const drinks = await suggestDrinks(
-    {
-      title: recipe.title,
-      description: recipe.description,
-      difficulty: recipe.difficulty,
-      dietaryTags: recipe.dietaryTags as Record<string, boolean> | null,
-      ingredients: recipe.ingredients,
-    },
-    parsed.data.count,
-    { ...aiConfig, userContext: privateBio ?? undefined },
-    (session!.user as { locale?: string }).locale ?? "en"
-  );
 
-  return NextResponse.json({ drinks });
+  const result = await withAiQuota(session!.user.id, session!.user.tier as "free" | "pro", () =>
+    suggestDrinks(
+      {
+        title: recipe.title,
+        description: recipe.description,
+        difficulty: recipe.difficulty,
+        dietaryTags: recipe.dietaryTags as Record<string, boolean> | null,
+        ingredients: recipe.ingredients,
+      },
+      parsed.data.count,
+      { ...aiConfig, userContext: privateBio ?? undefined },
+      (session!.user as { locale?: string }).locale ?? "en"
+    )
+  );
+  if (!result.ok) return result.response;
+
+  return NextResponse.json({ drinks: result.data });
 }

apps/web/app/api/v1/ai/generate-from-idea/route.ts

@@ -2,7 +2,7 @@ import { NextRequest, NextResponse } from "next/server";
 import { z } from "zod";
 import { requireSession } from "@/lib/api-auth";
 import { applyRateLimit } from "@/lib/rate-limit";
-import { checkAndIncrementTierLimit } from "@/lib/tiers";
+import { withAiQuota } from "@/lib/ai/ai-error";
 import { generateRecipe } from "@/lib/ai/features/generate-recipe";
 import { getUserPrivateBio } from "@/lib/ai/user-bio";
 import { db, recipes, recipeIngredients, recipeSteps } from "@epicure/db";
@@ -29,17 +29,19 @@ export async function POST(req: NextRequest) {
   const limited = await applyRateLimit(`rl:ai:${session!.user.id}`, 10, 60);
   if (limited) return limited;
 
-  await checkAndIncrementTierLimit(session!.user.id, session!.user.tier as "free" | "pro", "aiCall");
-
   const privateBio = await getUserPrivateBio(session!.user.id);
   const locale = (session!.user as { locale?: string }).locale ?? "en";
 
-  const recipe = await generateRecipe(parsed.data.title, {
+  const result = await withAiQuota(session!.user.id, session!.user.tier as "free" | "pro", () =>
-    provider: parsed.data.provider,
+    generateRecipe(parsed.data.title, {
-    model: parsed.data.model,
+      provider: parsed.data.provider,
-    userContext: privateBio ?? undefined,
+      model: parsed.data.model,
-    language: LANG[locale] ?? "English",
+      userContext: privateBio ?? undefined,
-  });
+      language: LANG[locale] ?? "English",
+    })
+  );
+  if (!result.ok) return result.response;
+  const recipe = result.data;
 
   const recipeId = crypto.randomUUID();
 

apps/web/app/api/v1/ai/generate/route.ts

@@ -2,7 +2,7 @@ import { NextRequest, NextResponse } from "next/server";
 import { z } from "zod";
 import { requireSession } from "@/lib/api-auth";
 import { applyRateLimit } from "@/lib/rate-limit";
-import { checkAndIncrementTierLimit } from "@/lib/tiers";
+import { withAiQuota } from "@/lib/ai/ai-error";
 import { generateRecipe } from "@/lib/ai/features/generate-recipe";
 import { getUserPrivateBio } from "@/lib/ai/user-bio";
 
@@ -27,17 +27,18 @@ export async function POST(req: NextRequest) {
   const limited = await applyRateLimit(`rl:ai:${session!.user.id}`, 10, 60);
   if (limited) return limited;
 
-  await checkAndIncrementTierLimit(session!.user.id, session!.user.tier as "free" | "pro", "aiCall");
-
   const privateBio = await getUserPrivateBio(session!.user.id);
 
-  const recipe = await generateRecipe(parsed.data.prompt, {
+  const result = await withAiQuota(session!.user.id, session!.user.tier as "free" | "pro", () =>
-    provider: parsed.data.provider,
+    generateRecipe(parsed.data.prompt, {
-    model: parsed.data.model,
+      provider: parsed.data.provider,
-    language: parsed.data.language,
+      model: parsed.data.model,
-    difficulty: parsed.data.difficulty,
+      language: parsed.data.language,
-    userContext: privateBio ?? undefined,
+      difficulty: parsed.data.difficulty,
-  });
+      userContext: privateBio ?? undefined,
+    })
+  );
+  if (!result.ok) return result.response;
 
-  return NextResponse.json(recipe);
+  return NextResponse.json(result.data);
 }

apps/web/app/api/v1/ai/import-photo/route.ts

@@ -3,7 +3,7 @@ import { z } from "zod";
 import { db, recipes, recipeIngredients, recipeSteps } from "@epicure/db";
 import { requireSession } from "@/lib/api-auth";
 import { applyRateLimit } from "@/lib/rate-limit";
-import { checkAndIncrementTierLimit, TierLimitError } from "@/lib/tiers";
+import { withAiQuota } from "@/lib/ai/ai-error";
 import { importFromPhoto } from "@/lib/ai/features/import-photo";
 import { getModelConfigForUseCase } from "@/lib/ai/resolve-user-key";
 
@@ -28,15 +28,6 @@ export async function POST(req: NextRequest) {
   const userId = session!.user.id;
   const locale = (session!.user as { locale?: string }).locale ?? "en";
 
-  try {
-    await checkAndIncrementTierLimit(userId, session!.user.tier as "free" | "pro", "aiCall");
-  } catch (err: unknown) {
-    if (err instanceof TierLimitError) {
-      return NextResponse.json({ error: "AI call limit reached for your tier" }, { status: 403 });
-    }
-    throw err;
-  }
-
   const aiConfig = await getModelConfigForUseCase(userId, "vision");
 
   // Fall back to vision-capable defaults if no explicit model configured
@@ -45,13 +36,11 @@ export async function POST(req: NextRequest) {
     else if (aiConfig.provider === "anthropic") aiConfig.model = "claude-sonnet-4-6";
   }
 
-  let recipe;
+  const result = await withAiQuota(userId, session!.user.tier as "free" | "pro", () =>
-  try {
+    importFromPhoto(parsed.data.imageBase64, parsed.data.mimeType, aiConfig, locale)
-    recipe = await importFromPhoto(parsed.data.imageBase64, parsed.data.mimeType, aiConfig, locale);
+  );
-  } catch (err: unknown) {
+  if (!result.ok) return result.response;
-    const msg = err instanceof Error ? err.message : "AI analysis failed";
+  const recipe = result.data;
-    return NextResponse.json({ error: msg }, { status: 502 });
-  }
 
   const newRecipeId = crypto.randomUUID();
   const now = new Date();

apps/web/app/api/v1/ai/import-url/route.ts

@@ -2,7 +2,7 @@ import { NextRequest, NextResponse } from "next/server";
 import { z } from "zod";
 import { requireSession } from "@/lib/api-auth";
 import { applyRateLimit } from "@/lib/rate-limit";
-import { checkAndIncrementTierLimit } from "@/lib/tiers";
+import { withAiQuota } from "@/lib/ai/ai-error";
 import { importFromUrl } from "@/lib/ai/features/import-url";
 import { validateWebhookUrl } from "@/lib/validate-webhook-url";
 
@@ -30,12 +30,13 @@ export async function POST(req: NextRequest) {
   const limited = await applyRateLimit(`rl:ai:${session!.user.id}`, 10, 60);
   if (limited) return limited;
 
-  await checkAndIncrementTierLimit(session!.user.id, session!.user.tier as "free" | "pro", "aiCall");
+  const result = await withAiQuota(session!.user.id, session!.user.tier as "free" | "pro", () =>
+    importFromUrl(parsed.data.url, {
+      provider: parsed.data.provider,
+      model: parsed.data.model,
+    })
+  );
+  if (!result.ok) return result.response;
 
-  const recipe = await importFromUrl(parsed.data.url, {
+  return NextResponse.json(result.data);
-    provider: parsed.data.provider,
-    model: parsed.data.model,
-  });
-
-  return NextResponse.json(recipe);
 }

apps/web/app/api/v1/ai/meal-plan/generate/route.ts

@@ -4,6 +4,7 @@ import { db, recipes, recipeIngredients, recipeSteps, mealPlans, mealPlanEntries
 import { requireSession } from "@/lib/api-auth";
 import { applyRateLimit } from "@/lib/rate-limit";
 import { getDefaultProviderWithKey } from "@/lib/ai/resolve-user-key";
+import { aiErrorResponse } from "@/lib/ai/ai-error";
 import { generateMealPlan } from "@/lib/ai/features/generate-meal-plan";
 import { getUserPrivateBio } from "@/lib/ai/user-bio";
 
@@ -52,18 +53,23 @@ export async function POST(req: NextRequest) {
     pantryItemNames = pantry.map((p) => p.rawName);
   }
 
-  const plan = await generateMealPlan(
+  let plan;
-    {
+  try {
-      dietaryPrefs: parsed.data.dietaryPrefs,
+    plan = await generateMealPlan(
-      servings: parsed.data.servings,
+      {
-      pantryItems: pantryItemNames,
+        dietaryPrefs: parsed.data.dietaryPrefs,
-      days: parsed.data.days,
+        servings: parsed.data.servings,
-      pantryMode: parsed.data.pantryMode,
+        pantryItems: pantryItemNames,
-      difficulty: parsed.data.difficulty,
+        days: parsed.data.days,
-    },
+        pantryMode: parsed.data.pantryMode,
-    { ...config, userContext: privateBio ?? undefined },
+        difficulty: parsed.data.difficulty,
-    locale
+      },
-  );
+      { ...config, userContext: privateBio ?? undefined },
+      locale
+    );
+  } catch (err) {
+    return aiErrorResponse(err);
+  }
 
   // Ensure meal plan row exists for the week
   let mealPlan = await db.query.mealPlans.findFirst({

apps/web/app/api/v1/ai/pairings/[id]/route.ts

@@ -3,7 +3,7 @@ import { z } from "zod";
 import { and, eq } from "@epicure/db";
 import { db, recipes } from "@epicure/db";
 import { requireSession } from "@/lib/api-auth";
-import { checkAndIncrementTierLimit } from "@/lib/tiers";
+import { withAiQuota } from "@/lib/ai/ai-error";
 import { suggestPairings } from "@/lib/ai/features/suggest-pairings";
 import { withUserKey } from "@/lib/ai/resolve-user-key";
 import { getUserPrivateBio } from "@/lib/ai/user-bio";
@@ -35,24 +35,26 @@ export async function POST(req: NextRequest, { params }: Params) {
   const parsed = Schema.safeParse(body ?? {});
   if (!parsed.success) return NextResponse.json({ error: "Validation error" }, { status: 400 });
 
-  await checkAndIncrementTierLimit(session!.user.id, session!.user.tier as "free" | "pro", "aiCall");
-
   const [aiConfig, privateBio] = await Promise.all([
     withUserKey(session!.user.id, { provider: parsed.data.provider, model: parsed.data.model }),
     getUserPrivateBio(session!.user.id),
   ]);
-  const pairings = await suggestPairings(
-    {
-      title: recipe.title,
-      description: recipe.description,
-      difficulty: recipe.difficulty,
-      dietaryTags: recipe.dietaryTags as Record<string, boolean> | null,
-      ingredients: recipe.ingredients,
-    },
-    parsed.data.count,
-    { ...aiConfig, userContext: privateBio ?? undefined },
-    (session!.user as { locale?: string }).locale ?? "en"
-  );
 
-  return NextResponse.json({ pairings });
+  const result = await withAiQuota(session!.user.id, session!.user.tier as "free" | "pro", () =>
+    suggestPairings(
+      {
+        title: recipe.title,
+        description: recipe.description,
+        difficulty: recipe.difficulty,
+        dietaryTags: recipe.dietaryTags as Record<string, boolean> | null,
+        ingredients: recipe.ingredients,
+      },
+      parsed.data.count,
+      { ...aiConfig, userContext: privateBio ?? undefined },
+      (session!.user as { locale?: string }).locale ?? "en"
+    )
+  );
+  if (!result.ok) return result.response;
+
+  return NextResponse.json({ pairings: result.data });
 }

apps/web/app/api/v1/ai/scale/route.ts

@@ -4,7 +4,7 @@ import { db, recipes, eq, and, or } from "@epicure/db";
 import { requireSession } from "@/lib/api-auth";
 import { applyRateLimit } from "@/lib/rate-limit";
 import { getDefaultProviderWithKey } from "@/lib/ai/resolve-user-key";
-import { checkAndIncrementTierLimit } from "@/lib/tiers";
+import { withAiQuota } from "@/lib/ai/ai-error";
 import { scaleRecipe } from "@/lib/ai/features/scale-recipe";
 
 const Schema = z.object({
@@ -40,21 +40,22 @@ export async function POST(req: NextRequest) {
     return NextResponse.json({ error: "Not found" }, { status: 404 });
   }
 
-  await checkAndIncrementTierLimit(session!.user.id, session!.user.tier as "free" | "pro", "aiCall");
-
   const aiConfig = await getDefaultProviderWithKey(session!.user.id);
 
-  const scaledIngredients = await scaleRecipe(
+  const result = await withAiQuota(session!.user.id, session!.user.tier as "free" | "pro", () =>
-    {
+    scaleRecipe(
-      title: recipe.title,
+      {
-      baseServings: recipe.baseServings,
+        title: recipe.title,
-      ingredients: recipe.ingredients,
+        baseServings: recipe.baseServings,
-    },
+        ingredients: recipe.ingredients,
-    targetServings,
+      },
-    recipe.baseServings,
+      targetServings,
-    aiConfig,
+      recipe.baseServings,
-    (session!.user as { locale?: string }).locale ?? "en"
+      aiConfig,
+      (session!.user as { locale?: string }).locale ?? "en"
+    )
   );
+  if (!result.ok) return result.response;
 
-  return NextResponse.json({ ingredients: scaledIngredients });
+  return NextResponse.json({ ingredients: result.data });
 }

apps/web/app/api/v1/ai/substitute/route.ts

@@ -1,7 +1,7 @@
 import { NextRequest, NextResponse } from "next/server";
 import { z } from "zod";
 import { requireSession } from "@/lib/api-auth";
-import { checkAndIncrementTierLimit, TierLimitError } from "@/lib/tiers";
+import { withAiQuota } from "@/lib/ai/ai-error";
 import { applyRateLimit } from "@/lib/rate-limit";
 import { getDefaultProviderWithKey } from "@/lib/ai/resolve-user-key";
 import { substituteIngredient } from "@/lib/ai/features/substitute-ingredient";
@@ -24,15 +24,6 @@ export async function POST(req: NextRequest) {
   const rateLimitRes = await applyRateLimit(`ai:substitute:${session!.user.id}`, 10, 60);
   if (rateLimitRes) return rateLimitRes;
 
-  try {
-    await checkAndIncrementTierLimit(session!.user.id, session!.user.tier as "free" | "pro", "aiCall");
-  } catch (err) {
-    if (err instanceof TierLimitError) {
-      return NextResponse.json({ error: "AI call limit reached for your tier" }, { status: 403 });
-    }
-    throw err;
-  }
-
   const context = parsed.data.recipeTitle
     ? `recipe "${parsed.data.recipeTitle}"`
     : "a general recipe";
@@ -43,12 +34,10 @@ export async function POST(req: NextRequest) {
 
   const locale = (session!.user as { locale?: string }).locale ?? "en";
 
-  const substitutions = await substituteIngredient(
+  const result = await withAiQuota(session!.user.id, session!.user.tier as "free" | "pro", () =>
-    parsed.data.ingredient,
+    substituteIngredient(parsed.data.ingredient, context, aiConfig, locale)
-    context,
-    aiConfig,
-    locale
   );
+  if (!result.ok) return result.response;
 
-  return NextResponse.json({ substitutions });
+  return NextResponse.json({ substitutions: result.data });
 }

apps/web/app/api/v1/ai/translate/[id]/route.ts

@@ -3,7 +3,7 @@ import { z } from "zod";
 import { and, eq } from "@epicure/db";
 import { db, recipes, recipeIngredients, recipeSteps } from "@epicure/db";
 import { requireSession } from "@/lib/api-auth";
-import { checkAndIncrementTierLimit } from "@/lib/tiers";
+import { withAiQuota } from "@/lib/ai/ai-error";
 import { translateRecipe } from "@/lib/ai/features/translate-recipe";
 
 const Schema = z.object({
@@ -35,18 +35,20 @@ export async function POST(req: NextRequest, { params }: Params) {
     return NextResponse.json({ error: "Validation error", issues: parsed.error.issues }, { status: 400 });
   }
 
-  await checkAndIncrementTierLimit(session!.user.id, session!.user.tier as "free" | "pro", "aiCall");
+  const result = await withAiQuota(session!.user.id, session!.user.tier as "free" | "pro", () =>
-
+    translateRecipe(
-  const translation = await translateRecipe(
+      {
-    {
+        title: recipe.title,
-      title: recipe.title,
+        description: recipe.description,
-      description: recipe.description,
+        ingredients: recipe.ingredients,
-      ingredients: recipe.ingredients,
+        steps: recipe.steps,
-      steps: recipe.steps,
+      },
-    },
+      parsed.data.targetLanguage,
-    parsed.data.targetLanguage,
+      { provider: parsed.data.provider, model: parsed.data.model }
-    { provider: parsed.data.provider, model: parsed.data.model }
+    )
   );
+  if (!result.ok) return result.response;
+  const translation = result.data;
 
   // Save as new draft recipe
   const newId = crypto.randomUUID();

apps/web/app/api/v1/ai/variations/[id]/route.ts

@@ -3,7 +3,7 @@ import { z } from "zod";
 import { and, eq } from "@epicure/db";
 import { db, recipes } from "@epicure/db";
 import { requireSession } from "@/lib/api-auth";
-import { checkAndIncrementTierLimit } from "@/lib/tiers";
+import { withAiQuota } from "@/lib/ai/ai-error";
 import { suggestVariations } from "@/lib/ai/features/suggest-variations";
 import { withUserKey } from "@/lib/ai/resolve-user-key";
 import { getUserPrivateBio } from "@/lib/ai/user-bio";
@@ -38,24 +38,26 @@ export async function POST(req: NextRequest, { params }: Params) {
     return NextResponse.json({ error: "Validation error", issues: parsed.error.issues }, { status: 400 });
   }
 
-  await checkAndIncrementTierLimit(session!.user.id, session!.user.tier as "free" | "pro", "aiCall");
-
   const [aiConfig, privateBio] = await Promise.all([
     withUserKey(session!.user.id, { provider: parsed.data.provider, model: parsed.data.model }),
     getUserPrivateBio(session!.user.id),
   ]);
-  const variations = await suggestVariations(
-    {
-      title: recipe.title,
-      description: recipe.description,
-      ingredients: recipe.ingredients,
-      steps: recipe.steps,
-    },
-    parsed.data.count,
-    { ...aiConfig, userContext: privateBio ?? undefined },
-    parsed.data.directions,
-    (session!.user as { locale?: string }).locale ?? "en"
-  );
 
-  return NextResponse.json({ variations });
+  const result = await withAiQuota(session!.user.id, session!.user.tier as "free" | "pro", () =>
+    suggestVariations(
+      {
+        title: recipe.title,
+        description: recipe.description,
+        ingredients: recipe.ingredients,
+        steps: recipe.steps,
+      },
+      parsed.data.count,
+      { ...aiConfig, userContext: privateBio ?? undefined },
+      parsed.data.directions,
+      (session!.user as { locale?: string }).locale ?? "en"
+    )
+  );
+  if (!result.ok) return result.response;
+
+  return NextResponse.json({ variations: result.data });
 }

apps/web/lib/__tests__/tiers.test.ts

@@ -23,7 +23,7 @@ vi.mock("@epicure/db", () => ({
 }));
 
 // Import after mock
-const { checkAndIncrementTierLimit, incrementUsage } = await import("../tiers");
+const { checkAndIncrementTierLimit, incrementUsage, refundAiCall } = await import("../tiers");
 
 function makeChain(finalValue: unknown) {
   const chain = {
@@ -93,6 +93,14 @@ describe("checkAndIncrementTierLimit", () => {
   });
 });
 
+describe("refundAiCall", () => {
+  it("issues a decrement-with-floor UPDATE for the current month", async () => {
+    mockDb.execute.mockResolvedValueOnce(undefined);
+    await refundAiCall("user1");
+    expect(mockDb.execute).toHaveBeenCalledTimes(1);
+  });
+});
+
 describe("incrementUsage", () => {
   it("calls insert with correct aiCall initial values", async () => {
     const chain = makeInsertChain();

apps/web/lib/ai/__tests__/ai-error.test.ts

@@ -0,0 +1,83 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { APICallError } from "ai";
+
+const { mockCheckAndIncrement, mockRefund } = vi.hoisted(() => ({
+  mockCheckAndIncrement: vi.fn(),
+  mockRefund: vi.fn().mockResolvedValue(undefined),
+}));
+
+vi.mock("@/lib/tiers", async () => {
+  const actual = await vi.importActual<typeof import("@/lib/tiers")>("@/lib/tiers");
+  return {
+    ...actual,
+    checkAndIncrementTierLimit: mockCheckAndIncrement,
+    refundAiCall: mockRefund,
+  };
+});
+
+const { aiErrorResponse, withAiQuota } = await import("../ai-error");
+const { TierLimitError } = await import("@/lib/tiers");
+
+beforeEach(() => {
+  vi.clearAllMocks();
+  mockCheckAndIncrement.mockResolvedValue(undefined);
+});
+
+function makeApiCallError(isRetryable: boolean) {
+  return new APICallError({
+    message: "Provider returned error",
+    url: "https://openrouter.ai/api/v1/responses",
+    requestBodyValues: {},
+    statusCode: isRetryable ? 503 : 400,
+    isRetryable,
+  });
+}
+
+describe("aiErrorResponse", () => {
+  it("maps a retryable APICallError to a 503 with a friendly message", async () => {
+    const res = aiErrorResponse(makeApiCallError(true));
+    expect(res.status).toBe(503);
+    const body = await res.json() as { error: string; retryable: boolean };
+    expect(body.retryable).toBe(true);
+    expect(body.error).not.toMatch(/openrouter|nvidia|nemotron/i);
+  });
+
+  it("maps a non-retryable APICallError to a 502", async () => {
+    const res = aiErrorResponse(makeApiCallError(false));
+    expect(res.status).toBe(502);
+    const body = await res.json() as { retryable: boolean };
+    expect(body.retryable).toBe(false);
+  });
+
+  it("maps an unknown error to a generic 502", async () => {
+    const res = aiErrorResponse(new Error("boom"));
+    expect(res.status).toBe(502);
+  });
+});
+
+describe("withAiQuota", () => {
+  it("returns 403 when the tier limit is already reached, without calling fn", async () => {
+    mockCheckAndIncrement.mockRejectedValue(new TierLimitError("aiCall", "free"));
+    const fn = vi.fn();
+    const result = await withAiQuota("user-1", "free", fn);
+    expect(result.ok).toBe(false);
+    if (!result.ok) expect(result.response.status).toBe(403);
+    expect(fn).not.toHaveBeenCalled();
+  });
+
+  it("refunds the charged credit when fn throws", async () => {
+    const fn = vi.fn().mockRejectedValue(makeApiCallError(true));
+    const result = await withAiQuota("user-1", "free", fn);
+    expect(result.ok).toBe(false);
+    expect(mockRefund).toHaveBeenCalledWith("user-1");
+    if (!result.ok) expect(result.response.status).toBe(503);
+  });
+
+  it("returns fn's result and does not refund on success", async () => {
+    const fn = vi.fn().mockResolvedValue({ title: "Pasta" });
+    const result = await withAiQuota("user-1", "free", fn);
+    expect(result.ok).toBe(true);
+    if (result.ok) expect(result.data).toEqual({ title: "Pasta" });
+    expect(mockRefund).not.toHaveBeenCalled();
+  });
+});

apps/web/lib/ai/ai-error.ts

@@ -0,0 +1,55 @@
+import { NextResponse } from "next/server";
+import { APICallError } from "ai";
+import { checkAndIncrementTierLimit, refundAiCall, TierLimitError } from "@/lib/tiers";
+
+/**
+ * Maps an AI-call failure to a clean JSON response instead of letting the
+ * raw provider error (which can include internal provider names/payloads)
+ * reach the client or crash the route as an uncaught 500.
+ */
+export function aiErrorResponse(err: unknown): NextResponse {
+  if (APICallError.isInstance(err)) {
+    return NextResponse.json(
+      {
+        error: err.isRetryable
+          ? "The AI provider is temporarily unavailable. Please try again in a moment."
+          : "The AI provider rejected this request. Try switching models in Settings.",
+        retryable: err.isRetryable,
+      },
+      { status: err.isRetryable ? 503 : 502 }
+    );
+  }
+
+  return NextResponse.json({ error: "AI request failed. Please try again." }, { status: 502 });
+}
+
+type QuotaResult<T> = { ok: true; data: T } | { ok: false; response: NextResponse };
+
+/**
+ * Charges one aiCall credit, runs `fn`, and refunds the credit if `fn`
+ * throws — so a provider outage never silently burns a user's quota.
+ * Centralizes the TierLimitError → 403 and AI-failure → clean-JSON mapping
+ * that every AI route needs instead of repeating try/catch per route.
+ */
+export async function withAiQuota<T>(
+  userId: string,
+  tier: "free" | "pro",
+  fn: () => Promise<T>
+): Promise<QuotaResult<T>> {
+  try {
+    await checkAndIncrementTierLimit(userId, tier, "aiCall");
+  } catch (err) {
+    if (err instanceof TierLimitError) {
+      return { ok: false, response: NextResponse.json({ error: "AI call limit reached for your tier" }, { status: 403 }) };
+    }
+    throw err;
+  }
+
+  try {
+    const data = await fn();
+    return { ok: true, data };
+  } catch (err) {
+    await refundAiCall(userId);
+    return { ok: false, response: aiErrorResponse(err) };
+  }
+}

apps/web/lib/tiers.ts

@@ -69,6 +69,20 @@ export async function checkAndIncrementTierLimit(
   }
 }
 
+/**
+ * Refunds one aiCall credit for the current month. Call this when an AI
+ * request failed after the quota was already charged (e.g. provider error)
+ * so users aren't billed against their limit for a call that never succeeded.
+ */
+export async function refundAiCall(userId: string): Promise<void> {
+  const month = currentMonth();
+  await db.execute(sql`
+    UPDATE user_usage
+    SET ai_calls_used = GREATEST(ai_calls_used - 1, 0)
+    WHERE user_id = ${userId} AND month = ${month}
+  `);
+}
+
 export async function incrementUsage(
   userId: string,
   key: LimitKey,