fix(ramp): route swallowed getUserLimits errors through failSession (Phase 9.5 Fix A)

useTransakRouting.checkUserLimits previously caught errors from
getUserLimits, rethrew LimitExceededError, and swallowed every other
error (Logger.error). In headless mode the consumer got no onError
callback when this fired for an infrastructure failure (network blip,
malformed response), leaving the session hung.

Resolution: in the catch, gate the new behavior on headlessSessionId:

  if (error instanceof LimitExceededError) throw error;
  if (headlessSessionId) {
    failSession(headlessSessionId, error);
    throw error;
  }
  Logger.error(error as Error, 'Failed to check user limits');

UB2's existing swallow is preserved — the existing test
'logs error and returns when getUserLimits throws a non-limit error'
encodes the swallow as intent and continues to pass. Two new tests
cover (a) failSession invoked + rethrow propagates in headless mode and
(b) LimitExceededError short-circuits before failSession.

The parallel getUserLimits swallow in useDepositRouting.ts:137-180 is
deliberately left untouched (Deposit is not a headless route, and the
"ramps work is UB2-only" rule keeps us off the Deposit tree).

Author: saustrie-consensys

CHANGELOG.md

@@ -11,6 +11,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - Made the Ramp Headless Host invisible so consumer-rendered loading UI is visible during a headless buy; added a transparent `RAMP.HEADLESS_ENTRY` outer route so the headless flow no longer renders an opaque V2 stack card on top of the consumer screen (Phase 9.5).
 
+### Fixed
+
+- Route swallowed `getUserLimits` infrastructure errors through `failSession` when a headless Ramp session is active, so headless consumers receive an `onError` callback instead of a silent hang (Phase 9.5 Fix A).
+
 ## [7.76.3]
 
 ### Added

app/components/UI/Ramp/headless/PLAN.md

@@ -648,6 +648,29 @@ This is the same pattern MainNavigator already uses for `BridgeModals`, `EarnMod
 
 Safety net for the unverified `beforeRemove` + `transparentModal` interaction: Phase 8's `useHeadlessSessionDismissal` fires `closeSession({ reason: 'user_dismissed' })` on unmount when `HEADLESS_HOST` is no longer in the navigator tree. `closeSession` idempotency means both paths can fire without producing duplicate `onClose` callbacks.
 
+#### Fix A — `getUserLimits` swallow → `failSession` (conditional rethrow)
+
+[useTransakRouting.ts:241-256](../hooks/useTransakRouting.ts) (`checkUserLimits`) catches errors from `getUserLimits`, rethrows `LimitExceededError`, and **swallows everything else** (network blips, malformed responses, etc.). In headless mode the consumer got no callback when this fired.
+
+Resolution: gate the new behavior on `headlessSessionId`:
+
+```ts
+} catch (error) {
+  if (error instanceof LimitExceededError) {
+    throw error;
+  }
+  if (headlessSessionId) {
+    failSession(headlessSessionId, error);
+    throw error;
+  }
+  Logger.error(error as Error, 'Failed to check user limits');
+}
+```
+
+UB2's existing swallow stays in place — the existing test at [useTransakRouting.test.ts:957-982](../hooks/useTransakRouting.test.ts) (`'logs error and returns when getUserLimits throws a non-limit error'`) encodes the swallow as intent and continues to pass. Two new tests cover the headless paths (`failSession` invoked + rethrow propagates; `LimitExceededError` short-circuits before `failSession`).
+
+The parallel swallow in [useDepositRouting.ts:137-180](../hooks/useDepositRouting.ts) is deliberately **not** fixed here — Deposit isn't a headless route, and the "ramps work is UB2-only" rule keeps us off the Deposit tree.
+
 ---
 
 ## Phase 10 — Implement deferred Phase 5b + playground polish

app/components/UI/Ramp/hooks/useTransakRouting.test.ts

@@ -980,6 +980,95 @@ describe('useTransakRouting', () => {
 
       expect(mockRequestOtt).toHaveBeenCalled();
     });
+
+    it('routes getUserLimits infrastructure errors through failSession when headlessSessionId is set', async () => {
+      const mockFailSession = jest.requireMock('../headless/sessionRegistry')
+        .failSession as jest.Mock;
+      mockGetUserDetails.mockResolvedValue({
+        firstName: 'John',
+        address: {},
+      });
+      mockGetKycRequirement.mockResolvedValue({
+        status: 'APPROVED',
+        kycType: 'SIMPLE',
+      });
+      const networkError = new Error('Network failure');
+      mockGetUserLimits.mockRejectedValue(networkError);
+      mockRequestOtt.mockResolvedValue({ ott: 'test-ott' });
+      mockGeneratePaymentWidgetUrl.mockReturnValue(
+        'https://payment.example.com',
+      );
+
+      const { result } = renderHook(() =>
+        useTransakRouting({
+          baseRoute: 'RampHeadlessHost',
+          baseRouteParams: { headlessSessionId: 'headless-buy-fixa' },
+        }),
+      );
+
+      // The rethrow propagates through the outer `case 'APPROVED'` catch,
+      // which re-wraps as `parseUserFacingError`. We catch the rejection
+      // inside act so all microtasks settle before the assertion.
+      let caught: unknown;
+      await act(async () => {
+        try {
+          await result.current.routeAfterAuthentication(
+            mockQuote as never,
+            mockQuote.fiatAmount,
+          );
+        } catch (e) {
+          caught = e;
+        }
+      });
+      expect(caught).toBeInstanceOf(Error);
+
+      expect(mockFailSession).toHaveBeenCalledWith(
+        'headless-buy-fixa',
+        networkError,
+      );
+      // The rethrow unwinds the flow before reaching OTT generation.
+      expect(mockRequestOtt).not.toHaveBeenCalled();
+    });
+
+    it('does not call failSession when LimitExceededError fires in headless mode (early rethrow wins)', async () => {
+      const mockFailSession = jest.requireMock('../headless/sessionRegistry')
+        .failSession as jest.Mock;
+      mockFailSession.mockReset();
+      mockGetUserDetails.mockResolvedValue({
+        firstName: 'John',
+        address: {},
+      });
+      mockGetKycRequirement.mockResolvedValue({
+        status: 'APPROVED',
+        kycType: 'SIMPLE',
+      });
+      // Returning daily remaining=0 forces the inner code path to throw
+      // LimitExceededError before the generic catch sees it.
+      mockGetUserLimits.mockResolvedValue({
+        remaining: { '1': 0, '30': 50000, '365': 200000 },
+      });
+
+      const { result } = renderHook(() =>
+        useTransakRouting({
+          baseRoute: 'RampHeadlessHost',
+          baseRouteParams: { headlessSessionId: 'headless-buy-fixa-limit' },
+        }),
+      );
+
+      await expect(
+        act(async () => {
+          await result.current.routeAfterAuthentication(
+            mockQuote as never,
+            mockQuote.fiatAmount,
+          );
+        }),
+      ).rejects.toThrow();
+
+      // LimitExceededError takes the early rethrow path — failSession isn't
+      // invoked because the limit error is a user-actionable condition that
+      // the outer flow handles directly.
+      expect(mockFailSession).not.toHaveBeenCalled();
+    });
   });
 
   describe('navigateToVerifyIdentity', () => {

app/components/UI/Ramp/hooks/useTransakRouting.ts

@@ -242,10 +242,20 @@ export const useTransakRouting = (config?: UseTransakRoutingConfig) => {
         if (error instanceof LimitExceededError) {
           throw error;
         }
+        if (headlessSessionId) {
+          // Headless mode: route the swallowed infrastructure error through
+          // the session so the consumer receives an onError callback, then
+          // rethrow so the caller's outer catch unwinds the flow.
+          failSession(headlessSessionId, error);
+          throw error;
+        }
+        // Non-headless (UB2) preserves today's swallow — the existing test
+        // 'logs error and returns when getUserLimits throws a non-limit
+        // error' encodes that as intent.
         Logger.error(error as Error, 'Failed to check user limits');
       }
     },
-    [getUserLimits, fiatCurrency, selectedPaymentMethod?.id],
+    [getUserLimits, fiatCurrency, selectedPaymentMethod?.id, headlessSessionId],
   );
 
   const navigateToVerifyIdentityCallback = useCallback(