MetaMask · saustrie-consensys · Apr 29, 2026 · Apr 29, 2026 · Apr 29, 2026 · Apr 29, 2026
@@ -246,6 +246,9 @@ const USER_REGION = {
   regionCode: 'us-ca',
 };
 
+const CIRCUIT_BREAKER_MESSAGE =
+  'This service is temporarily unavailable. Please try again in about 30 minutes.';
+
 const buildProviderWithLimits = (limits: {
   minAmount: number;
   maxAmount: number;
@@ -982,6 +985,61 @@ describe('BuildQuote', () => {
         getByTestId(BuildQuoteSelectors.CONTINUE_BUTTON),
       ).toBeOnTheScreen();
     });
+
+    it('shows the localized circuit breaker fallback for quote fetch errors', () => {
+      const circuitBreakerError = Object.assign(
+        new Error('Execution prevented because the circuit breaker is open'),
+        { errorKey: 'CIRCUIT_BREAKER_OPEN' },
+      );
+      mockUseRampsQuotes.mockReturnValue({
+        data: null,
+        loading: false,
+        error: circuitBreakerError,
+      });
+
+      const { getByText, queryByText } = renderWithProvider(<BuildQuote />, {
+        state: initialRootState,
+      });
+
+      expect(getByText(CIRCUIT_BREAKER_MESSAGE)).toBeOnTheScreen();
+      expect(
+        queryByText('Execution prevented because the circuit breaker is open'),
+      ).not.toBeOnTheScreen();
+      expect(mockAddProperties).toHaveBeenCalledWith(
+        expect.objectContaining({
+          error_message: CIRCUIT_BREAKER_MESSAGE,
+        }),
+      );
+    });
+
+    it('removes the quote fetch banner after quote fetching recovers', () => {
+      const quoteFetchError = new Error('Quote fetch failed');
+      let quotesHookResult: {
+        data: { success: (typeof WIDGET_PROVIDER_QUOTE)[] } | null;
+        loading: boolean;
+        error: Error | null;
+      } = {
+        data: null,
+        loading: false,
+        error: quoteFetchError,
+      };
+      mockUseRampsQuotes.mockImplementation(() => quotesHookResult);
+
+      const { queryByText, rerender } = renderWithProvider(<BuildQuote />, {
+        state: initialRootState,
+      });
+
+      expect(queryByText('Quote fetch failed')).toBeOnTheScreen();
+
+      quotesHookResult = {
+        data: { success: [WIDGET_PROVIDER_QUOTE] },
+        loading: false,
+        error: null,
+      };
+      rerender(<BuildQuote />);
+
+      expect(queryByText('Quote fetch failed')).not.toBeOnTheScreen();
+    });
   });
 
   describe('provider quote error (out-of-bounds / limits)', () => {

@@ -458,14 +458,15 @@ function BuildQuote() {
     loading: selectedQuoteLoading,
     error: quoteFetchError,
   } = useRampsQuotes(quoteFetchEnabled ? quoteFetchParams : null);
+  const hasQuoteFetchError = quoteFetchError !== null;
 
   /*
    * Tracks RAMPS_QUOTE_ERROR
    */
   const lastTrackedQuoteErrorRef = useRef<unknown>(null);
   useEffect(() => {
     if (
-      quoteFetchError &&
+      hasQuoteFetchError &&
       quoteFetchError !== lastTrackedQuoteErrorRef.current
     ) {
       lastTrackedQuoteErrorRef.current = quoteFetchError;
@@ -487,10 +488,11 @@ function BuildQuote() {
           .build(),
       );
     }
-    if (!quoteFetchError) {
+    if (!hasQuoteFetchError) {
       lastTrackedQuoteErrorRef.current = null;
     }
   }, [
+    hasQuoteFetchError,
     quoteFetchError,
     amountAsNumber,
     currency,
@@ -676,7 +678,7 @@ function BuildQuote() {
     hasAmount &&
     hasSettledQuoteAmount &&
     !selectedQuoteLoading &&
-    !quoteFetchError &&
+    !hasQuoteFetchError &&
     quotesResponse !== null &&
     selectedQuote === null;
 
@@ -834,15 +836,15 @@ function BuildQuote() {
             </View>
           </View>
 
-          {quoteFetchError && (
+          {hasQuoteFetchError ? (
             <BannerAlert
               severity={BannerAlertSeverity.Error}
               description={parseUserFacingError(
                 quoteFetchError,
                 strings('deposit.buildQuote.quoteFetchError'),
               )}
             />
-          )}
+          ) : null}
 
           <View style={styles.actionSection}>
             {hasAmount ? (

@@ -22,10 +22,12 @@ import { getOrdersProviders } from '../../../../../../reducers/fiatOrders';
 import { selectRampsOrdersForSelectedAccountGroup } from '../../../../../../selectors/rampsController';
 import { completedOrdersFromRampsOrders } from '../../../utils/determinePreferredProvider';
 import { providerSupportsAsset } from '../../../utils/providerSupportsAsset';
+import { parseUserFacingError } from '../../../utils/parseUserFacingError';
 import { useStyles } from '../../../../../hooks/useStyles';
 import styleSheet from './ProviderSelectionModal.styles';
 import { useAnalytics } from '../../../../../hooks/useAnalytics/useAnalytics';
 import { MetaMetricsEvents } from '../../../../../../core/Analytics';
+import { strings } from '../../../../../../../locales/i18n';
 
 export interface ProviderSelectionModalParams {
   amount?: number;
@@ -184,7 +186,14 @@ function ProviderSelectionModal() {
           providers={displayProviders}
           quotes={quotes}
           quotesLoading={quotesLoading}
-          quotesError={quotesError}
+          quotesError={
+            quotesError
+              ? parseUserFacingError(
+                  quotesError,
+                  strings('fiat_on_ramp.no_quotes_available'),
+                )
+              : null
+          }
           showQuotes={!skipQuotes && amount > 0 && !!selectedPaymentMethod}
           showBackButton={hasPaymentModalInStack}
           ordersProviders={ordersProviders.filter(

@@ -5,6 +5,11 @@ import React from 'react';
 import { useRampsCountries } from './useRampsCountries';
 import { type Country } from '@metamask/ramps-controller';
 
+jest.mock('../../../../../locales/i18n', () => ({
+  strings: (key: string) => key,
+  locale: 'en',
+}));
+
 const mockCountries: Country[] = [
   {
     isoCode: 'US',
@@ -123,5 +128,17 @@ describe('useRampsCountries', () => {
       });
       expect(result.current.error).toBe('Network error');
     });
+
+    it('returns localized fallback when the countries state carries a circuit breaker errorKey', () => {
+      const store = createMockStore({
+        error: 'Execution prevented because the circuit breaker is open',
+        errorKey: 'CIRCUIT_BREAKER_OPEN',
+      });
+      const { result } = renderHook(() => useRampsCountries(), {
+        wrapper: wrapper(store),
+      });
+
+      expect(result.current.error).toBe('fiat_on_ramp.circuit_breaker_open');
+    });
   });
 });
@@ -1,6 +1,8 @@
 import { useSelector } from 'react-redux';
+import { strings } from '../../../../../locales/i18n';
 import { selectCountries } from '../../../../selectors/rampsController';
 import { type Country } from '@metamask/ramps-controller';
+import { parseUserFacingError } from '../utils/parseUserFacingError';
 
 /**
  * Result returned by the useRampsCountries hook.
@@ -27,12 +29,18 @@ export interface UseRampsCountriesResult {
  * @returns Countries state.
  */
 export function useRampsCountries(): UseRampsCountriesResult {
-  const { data: countries, isLoading, error } = useSelector(selectCountries);
+  const countriesState = useSelector(selectCountries);
+  const { data: countries, isLoading, error } = countriesState;
 
   return {
     countries,
     isLoading,
-    error,
+    error: error
+      ? parseUserFacingError(
+          countriesState,
+          strings('fiat_on_ramp.payment_error'),
+        )
+      : null,
   };
 }
 

@@ -7,6 +7,11 @@ import { useRampsPaymentMethods } from './useRampsPaymentMethods';
 import { type PaymentMethod } from '@metamask/ramps-controller';
 import Engine from '../../../../core/Engine';
 
+jest.mock('../../../../../locales/i18n', () => ({
+  strings: (key: string) => key,
+  locale: 'en',
+}));
+
 jest.mock('../../../../core/Engine', () => ({
   context: {
     RampsController: {
@@ -225,6 +230,30 @@ describe('useRampsPaymentMethods', () => {
     expect(result.current.paymentMethods).toEqual([]);
   });
 
+  it('returns localized fallback when the payment methods query trips the circuit breaker', async () => {
+    const store = createMockStore();
+    const { Wrapper } = createWrapper(store);
+
+    (
+      Engine.context.RampsController.getPaymentMethods as jest.Mock
+    ).mockRejectedValue(
+      Object.assign(
+        new Error('Execution prevented because the circuit breaker is open'),
+        { errorKey: 'CIRCUIT_BREAKER_OPEN' },
+      ),
+    );
+
+    const { result } = renderHook(() => useRampsPaymentMethods(), {
+      wrapper: Wrapper,
+    });
+
+    await waitFor(() => {
+      expect(result.current.status).toBe('error');
+    });
+
+    expect(result.current.error).toBe('fiat_on_ramp.circuit_breaker_open');
+  });
+
   it('calls Engine.context.RampsController.setSelectedPaymentMethod with full payment method object', () => {
     const store = createMockStore({
       providers: { ...baseRampsState.providers, selected: null },

@@ -1,6 +1,7 @@
 import { useCallback, useEffect, useMemo } from 'react';
 import { useQuery } from '@tanstack/react-query';
 import { useSelector } from 'react-redux';
+import { strings } from '../../../../../locales/i18n';
 import {
   selectPaymentMethods,
   selectProviders,
@@ -10,6 +11,7 @@ import {
 import { type PaymentMethod } from '@metamask/ramps-controller';
 import Engine from '../../../../core/Engine';
 import { rampsQueries } from '../queries';
+import { parseUserFacingError } from '../utils/parseUserFacingError';
 import { normalizeAssetIdForApi } from '../utils/normalizeAssetIdForApi';
 
 export type RampsQueryStatus = 'idle' | 'loading' | 'success' | 'error';
@@ -153,8 +155,11 @@ export function useRampsPaymentMethods(): UseRampsPaymentMethodsResult {
     status,
     isSuccess: status === 'success',
     error:
-      paymentMethodsQuery.error instanceof Error
-        ? paymentMethodsQuery.error.message
+      paymentMethodsQuery.error != null
+        ? parseUserFacingError(
+            paymentMethodsQuery.error,
+            strings('fiat_on_ramp.payment_error'),
+          )
         : null,
   };
 }

@@ -1,10 +1,6 @@
 import { renderHook, act } from '@testing-library/react-native';
 import { Provider } from 'react-redux';
-import {
-  QueryClient,
-  QueryClientProvider,
-  useQuery,
-} from '@tanstack/react-query';
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
 import { configureStore } from '@reduxjs/toolkit';
 import React from 'react';
 import { useRampsProviders } from './useRampsProviders';
@@ -13,6 +9,11 @@ import Engine from '../../../../core/Engine';
 import { determinePreferredProvider } from '../utils/determinePreferredProvider';
 import { getOrders, type FiatOrder } from '../../../../reducers/fiatOrders';
 
+jest.mock('../../../../../locales/i18n', () => ({
+  strings: (key: string) => key,
+  locale: 'en',
+}));
+
 jest.mock('../../../../core/Engine', () => ({
   context: {
     RampsController: {
@@ -27,6 +28,9 @@ jest.mock('@tanstack/react-query', () => ({
   useQuery: jest.fn(),
 }));
 
+const mockUseQuery = jest.requireMock('@tanstack/react-query')
+  .useQuery as jest.Mock;
+
 const mockSelectedAccountGroupAddresses: string[] = [];
 
 jest.mock(
@@ -133,8 +137,6 @@ describe('useRampsProviders', () => {
   });
 
   describe('providers query', () => {
-    const mockUseQuery = useQuery as jest.MockedFunction<typeof useQuery>;
-
     it('triggers providers query when regionCode is available', () => {
       const store = createMockStore();
       renderHook(() => useRampsProviders(), {
@@ -205,6 +207,37 @@ describe('useRampsProviders', () => {
       });
       expect(result.current.error).toBe('Network error');
     });
+
+    it('returns localized fallback when the provider state carries a circuit breaker errorKey', () => {
+      const store = createMockStore({
+        error: 'Execution prevented because the circuit breaker is open',
+        errorKey: 'CIRCUIT_BREAKER_OPEN',
+      });
+      const { result } = renderHook(() => useRampsProviders(), {
+        wrapper: wrapper(store),
+      });
+
+      expect(result.current.error).toBe('fiat_on_ramp.circuit_breaker_open');
+    });
+
+    it('returns localized fallback when the providers query carries a circuit breaker errorKey', () => {
+      const circuitBreakerError = Object.assign(
+        new Error('Execution prevented because the circuit breaker is open'),
+        { errorKey: 'CIRCUIT_BREAKER_OPEN' },
+      );
+      mockUseQuery.mockReturnValueOnce({
+        data: undefined,
+        error: circuitBreakerError,
+        isLoading: false,
+      } as never);
+
+      const store = createMockStore();
+      const { result } = renderHook(() => useRampsProviders(), {
+        wrapper: wrapper(store),
+      });
+
+      expect(result.current.error).toBe('fiat_on_ramp.circuit_breaker_open');
+    });
   });
 
   describe('selectedProvider state', () => {