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/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,