fix(billing): treat the per-user free valves as an org_limit denial

Local testing surfaced a coherence gap: hitting the free valve during a
session showed the generic "try again shortly" modal, while the cloud
pre-flight showed "Free usage used up / Add payment method" for the same
state. The valves only exist for unsubscribed orgs, so classify their 429
wording as org_limit — both paths now land on the free-tier upsell. The
free-tier copy drops the "billing period" over-claim (a daily valve resets
sooner) and carries the reset hint when the caller has one.

Generated-By: PostHog Code
Task-Id: 1039ea23-9930-44e2-9888-b05cf8b129ec

Author: adboio

packages/core/src/billing/usageLimitContent.test.ts

@@ -33,6 +33,16 @@ describe("usageLimitContent", () => {
     },
   );
 
+  it("includes the reset hint in the free-tier copy when available", () => {
+    const content = usageLimitContent({
+      cause: "org_limit",
+      resetLabel: "Resets in 3h",
+      subscribed: false,
+    });
+    expect(content.title).toBe("Free usage used up");
+    expect(content.description).toContain("Resets in 3h");
+  });
+
   it("renders generic copy without a billing CTA when the cause is unknown", () => {
     const content = usageLimitContent({
       cause: null,

packages/core/src/billing/usageLimitContent.ts

@@ -28,8 +28,9 @@ export function usageLimitContent(args: {
     if (subscribed === false) {
       return {
         title: "Free usage used up",
-        description:
-          "Your organization has used its included PostHog Code usage for this billing period. Add a payment method to keep going — you only pay for what you use.",
+        description: `Your organization has used up its included PostHog Code usage.${
+          resetLabel ? ` ${resetLabel}.` : ""
+        } Add a payment method to keep going — you only pay for what you use.`,
         actionLabel: "Add payment method",
         dismissLabel: "Not now",
       };

packages/core/src/sessions/sessionServicePromptRecovery.test.ts

@@ -155,6 +155,11 @@ describe("SessionService gateway billing denials", () => {
         "Your team has reached its PostHog Code usage limit for this billing period.",
       expectedShow: { cause: "org_limit" },
     },
+    {
+      case: "a free-tier valve 429",
+      message: "Rate limit exceeded: User burst rate limit exceeded",
+      expectedShow: { cause: "org_limit" },
+    },
     {
       case: "an unclassified rate limit",
       message: "[429] Too many requests",

packages/shared/src/errors.test.ts

@@ -111,6 +111,13 @@ describe("classifyGatewayLimitError", () => {
       "Your team has reached its usage limit for this billing period.",
       "org_limit",
     ],
+    [
+      // Per-user free valves fire only for unsubscribed orgs; the modal's
+      // subscribed bit picks the free-tier copy.
+      "Rate limit exceeded: User burst rate limit exceeded",
+      "org_limit",
+    ],
+    ["Rate limit exceeded: User sustained rate limit exceeded", "org_limit"],
   ])("classifies %j as %s", (message, expected) => {
     expect(classifyGatewayLimitError(message)).toBe(expected);
   });
@@ -127,8 +134,6 @@ describe("classifyGatewayLimitError", () => {
   it.each([
     "Rate limit exceeded",
     "Rate limit exceeded: Product rate limit exceeded",
-    // Per-user valves are a pre-cutover mechanism; generic copy handles them.
-    "Rate limit exceeded: User burst rate limit exceeded",
     "Your team has used its monthly PostHog AI credits.",
     "network down",
   ])("returns null for %j", (message) => {

packages/shared/src/errors.ts

@@ -81,6 +81,10 @@ const MODEL_GATE_PATTERNS = ["needs a paid posthog plan"] as const;
 const ORG_LIMIT_PATTERNS = [
   "reached its posthog code usage limit",
   "reached its usage limit for this billing period",
+  // Per-user free valves — billed orgs have none, so these always mean the
+  // free tier is used up.
+  "user burst rate limit exceeded",
+  "user sustained rate limit exceeded",
 ] as const;
 
 const FATAL_SESSION_ERROR_PATTERNS = [