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/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(
-    parsed.data.ingredient,
-    context,
-    aiConfig,
-    locale
+  const result = await withAiQuota(session!.user.id, session!.user.tier as "free" | "pro", () =>
+    substituteIngredient(parsed.data.ingredient, context, aiConfig, locale)
   );
+  if (!result.ok) return result.response;
 
-  return NextResponse.json({ substitutions });
+  return NextResponse.json({ substitutions: result.data });
 }