feat(loops): surface safety-limit errors distinctly to the user

Author: charlesvien

packages/api-client/src/index.ts

@@ -6,7 +6,9 @@ export {
   createLoop,
   destroyLoop,
   type LoopEndpoints,
+  type LoopSafetyLimitBody,
   type LoopSchemas,
+  LoopsApiError,
   listLoopRuns,
   listLoops,
   partialUpdateLoop,

packages/api-client/src/loops.test.ts

@@ -4,6 +4,7 @@ import {
   createLoop,
   destroyLoop,
   type LoopSchemas,
+  LoopsApiError,
   listLoopRuns,
   listLoops,
   partialUpdateLoop,
@@ -203,4 +204,43 @@ describe("loops client", () => {
       "[404]",
     );
   });
+
+  it("throws LoopsApiError carrying the parsed body on a rejected request", async () => {
+    const { fetcher } = fakeFetcher(
+      {
+        error: "loop_safety_limit",
+        code: "max_loops_per_team",
+        limit: 100,
+        detail: "This project has reached the limit of 100 loops.",
+      },
+      429,
+    );
+    const client = createApiClient(fetcher, BASE_URL);
+
+    const error = await createLoop(
+      client,
+      PROJECT_ID,
+      MINIMAL_LOOP_WRITE,
+    ).catch((e) => e);
+
+    expect(error).toBeInstanceOf(LoopsApiError);
+    expect((error as LoopsApiError).status).toBe(429);
+    const safetyLimit = (error as LoopsApiError).safetyLimit;
+    expect(safetyLimit?.code).toBe("max_loops_per_team");
+    expect(safetyLimit?.detail).toContain("100 loops");
+  });
+
+  it("leaves safetyLimit null for a generic (non-limit) error body", async () => {
+    const { fetcher } = fakeFetcher({ detail: "Something broke" }, 500);
+    const client = createApiClient(fetcher, BASE_URL);
+
+    const error = await createLoop(
+      client,
+      PROJECT_ID,
+      MINIMAL_LOOP_WRITE,
+    ).catch((e) => e);
+
+    expect(error).toBeInstanceOf(LoopsApiError);
+    expect((error as LoopsApiError).safetyLimit).toBeNull();
+  });
 });

packages/api-client/src/loops.ts

@@ -367,14 +367,65 @@ async function loopsRequest<T>(
   });
 
   if (!response.ok) {
-    throw new Error(
-      `Loops API request failed: ${method.toUpperCase()} ${path} [${response.status}]`,
+    throw new LoopsApiError(
+      method,
+      path,
+      response.status,
+      await readBody(response),
     );
   }
 
   return (await parseResponseData(response)) as T;
 }
 
+/** Machine-readable body of a rejected loop safety/abuse limit (see the backend's
+ * `_loop_limit_response`). `error === "loop_safety_limit"` is the stable marker. */
+export interface LoopSafetyLimitBody {
+  error: "loop_safety_limit";
+  code: string;
+  limit: number;
+  detail: string;
+}
+
+/** Error thrown for any non-2xx loops response, carrying the status and parsed body so
+ * callers can distinguish a safety-limit rejection from a generic failure. */
+export class LoopsApiError extends Error {
+  readonly status: number;
+  readonly body: unknown;
+
+  constructor(method: string, path: string, status: number, body: unknown) {
+    super(
+      `Loops API request failed: ${method.toUpperCase()} ${path} [${status}]`,
+    );
+    this.name = "LoopsApiError";
+    this.status = status;
+    this.body = body;
+  }
+
+  /** The parsed safety-limit body when this is a limit rejection, otherwise null. */
+  get safetyLimit(): LoopSafetyLimitBody | null {
+    const body = this.body;
+    if (
+      body != null &&
+      typeof body === "object" &&
+      (body as { error?: unknown }).error === "loop_safety_limit"
+    ) {
+      return body as LoopSafetyLimitBody;
+    }
+    return null;
+  }
+}
+
+async function readBody(response: Response): Promise<unknown> {
+  // Only called on the error path, where nothing else consumes the body, so read
+  // it directly rather than cloning.
+  try {
+    return await response.json();
+  } catch {
+    return null;
+  }
+}
+
 export async function listLoops(
   client: ApiClient,
   projectId: string,

packages/ui/src/features/loops/components/LoopForm.tsx

@@ -4,7 +4,7 @@ import {
   CaretRight,
   Check,
 } from "@phosphor-icons/react";
-import type { LoopSchemas } from "@posthog/api-client/loops";
+import { type LoopSchemas, LoopsApiError } from "@posthog/api-client/loops";
 import { SettingsOptionSelect } from "@posthog/ui/features/settings/SettingsOptionSelect";
 import { useSetHeaderContent } from "@posthog/ui/hooks/useSetHeaderContent";
 import { Button } from "@posthog/ui/primitives/Button";
@@ -125,6 +125,16 @@ export function LoopForm({ loop }: LoopFormProps) {
         navigateToLoopDetail(created.id);
       }
     } catch (error) {
+      const safetyLimit =
+        error instanceof LoopsApiError ? error.safetyLimit : null;
+      if (safetyLimit) {
+        // A safety/abuse ceiling, not a normal failure: tell the user plainly so they can
+        // course-correct (delete a loop, remove triggers) or contact support for a raise.
+        toast.error("Safety limit reached", {
+          description: safetyLimit.detail,
+        });
+        return;
+      }
       toast.error(isEdit ? "Failed to save loop" : "Failed to create loop", {
         description: error instanceof Error ? error.message : undefined,
       });