feat: surface rate-limit details from the AI backend

Map an upstream 429 to a clear "rate limited" message with the
retry-after delay, and 503/529 to an "overloaded" message, instead of
returning an opaque server error.

Author: josephschorr

api/ai.test.ts

@@ -0,0 +1,42 @@
+import { describe, expect, it } from "vitest";
+
+import { describeTurnError } from "./ai";
+
+describe("describeTurnError", () => {
+  it("maps a 429 with a Headers retry-after to a rate_limit error with timing", () => {
+    const err = Object.assign(new Error("Too Many Requests"), {
+      status: 429,
+      headers: new Headers({ "retry-after": "42" }),
+    });
+    const out = describeTurnError(err);
+    expect(out.code).toBe("rate_limit");
+    expect(out.message).toMatch(/rate limited/i);
+    expect(out.retryAfter).toBe(42);
+  });
+
+  it("reads retry-after from a plain-record headers object", () => {
+    const err = { status: 429, headers: { "retry-after": "10" }, message: "rl" };
+    const out = describeTurnError(err);
+    expect(out.code).toBe("rate_limit");
+    expect(out.retryAfter).toBe(10);
+  });
+
+  it("omits retryAfter when the header is missing or non-numeric", () => {
+    expect(describeTurnError({ status: 429, headers: {} }).retryAfter).toBeUndefined();
+    expect(
+      describeTurnError({ status: 429, headers: { "retry-after": "soon" } }).retryAfter,
+    ).toBeUndefined();
+  });
+
+  it("maps 503 and 529 to an overloaded error", () => {
+    expect(describeTurnError({ status: 503 }).code).toBe("overloaded");
+    expect(describeTurnError({ status: 529 }).code).toBe("overloaded");
+  });
+
+  it("falls back to a server_error with the message for other failures", () => {
+    expect(describeTurnError(new Error("boom"))).toEqual({
+      code: "server_error",
+      message: "boom",
+    });
+  });
+});

api/ai.ts

@@ -56,11 +56,50 @@ export async function handleAiRequest(args: {
     );
   } catch (err) {
     console.error("[api/ai] turn failed:", err);
-    sink.send("error", { code: "server_error", message: (err as Error).message });
+    sink.send("error", describeTurnError(err));
     sink.end();
   }
 }
 
+// Reads the `retry-after` header (seconds) from an upstream error, tolerating
+// both a Headers object and a plain record.
+function retryAfterSeconds(err: unknown): number | undefined {
+  const headers = (err as { headers?: unknown }).headers;
+  let raw: string | null | undefined;
+  if (headers && typeof (headers as Headers).get === "function") {
+    raw = (headers as Headers).get("retry-after");
+  } else if (headers && typeof headers === "object") {
+    raw = (headers as Record<string, string>)["retry-after"];
+  }
+  const n = Number(raw);
+  return Number.isFinite(n) && n > 0 ? n : undefined;
+}
+
+// Maps an error thrown during the turn to a client-facing SSE error. Upstream
+// rate limits and overloads get a clear, actionable message (and retry timing)
+// instead of an opaque failure.
+export function describeTurnError(err: unknown): {
+  code: string;
+  message: string;
+  retryAfter?: number;
+} {
+  const status = (err as { status?: number }).status;
+  if (status === 429) {
+    return {
+      code: "rate_limit",
+      message: "The AI service is rate limited. Please wait a moment and try again.",
+      retryAfter: retryAfterSeconds(err),
+    };
+  }
+  if (status === 503 || status === 529) {
+    return {
+      code: "overloaded",
+      message: "The AI service is temporarily overloaded. Please try again shortly.",
+    };
+  }
+  return { code: "server_error", message: (err as Error).message || "The request failed." };
+}
+
 function clientIp(req: VercelRequest): string {
   const realIp = req.headers["x-real-ip"];
   if (typeof realIp === "string" && realIp.trim()) return realIp.trim();