feat: handle HTTP 451 banned-Safe responses with a custom message

The Transaction Service now answers every Safe-scoped endpoint with HTTP
451 Unavailable For Legal Reasons when a Safe is banned from the indexer,
reporting the reason under `detail`.

`HttpErrorFactory` only reads `message` from an upstream error body, so
these responses reached clients as a 451 carrying the generic
`An error occurred`. Add `mapBannedSafeError`, which rewrites a 451
payload before the factory reads it, and apply it in the three datasources
that call the Transaction Service: `TransactionApi`, `SafeBalancesApi` and
`ExportApi`.

The mapping is scoped to those datasources rather than placed inside
`HttpErrorFactory` because 451 only carries this meaning for the
Transaction Service; every other upstream keeps forwarding its own
message unchanged.

The `should forward a %s error` cases in the Transaction Service specs
drew a random 4xx/5xx status that could land on 451, so they now exclude
it through a single shared helper and 451 gets its own dedicated case.

Refs: WA-2969
See: safe-global/safe-transaction-service#2966

Author: claude

docs/agents/ARCHITECTURE.md

@@ -240,6 +240,9 @@ Guard inventory:
 Each layer funnels exceptions through exactly one place.
 Datasources normalize any thrown error with `HttpErrorFactory` (`src/datasources/errors/http-error-factory.ts`) into a `DataSourceError` (`src/domain/errors/data-source.error.ts`), which carries a message safe to expose and an optional HTTP status code (defaulting to 503).
 `DataSourceErrorFilter` (`src/routes/common/filters/data-source-error.filter.ts`) is the only place that turns a `DataSourceError` into an HTTP response.
+`HttpErrorFactory` reads the upstream message from the response body's `message` key, so an upstream reporting it under another key yields a generic `An error occurred`.
+The Transaction Service's HTTP 451 for a banned Safe — returned by every Safe-scoped endpoint, with the reason under `detail` — is the one case handled explicitly: `mapBannedSafeError` (`src/datasources/errors/helpers/banned-safe.helper.ts`) rewrites that payload before the factory reads it, so the 451 reaches the client with a stable message rather than a generic one.
+It is applied by the three datasources that call the Transaction Service (`TransactionApi`, `SafeBalancesApi`, `ExportApi`) rather than inside `HttpErrorFactory`, because 451 only carries that meaning for that upstream.
 
 Validation failures funnel through `ZodErrorFilter` (`src/routes/common/filters/zod-error.filter.ts`), which distinguishes the two places a Zod error can originate.
 A `ZodErrorWithCode` from a route-level `ValidationPipe` (user input) returns 422 with the parsed issue.

src/datasources/errors/constants.ts

@@ -0,0 +1,21 @@
+// SPDX-License-Identifier: FSL-1.1-MIT
+
+/**
+ * HTTP 451 Unavailable For Legal Reasons.
+ *
+ * Declared here because Nest's `HttpStatus` enum does not include it.
+ * The Transaction Service returns it on every Safe-scoped endpoint when the
+ * Safe is banned from the indexer for legal reasons.
+ *
+ * @see https://github.com/safe-global/safe-transaction-service/pull/2966
+ */
+export const UNAVAILABLE_FOR_LEGAL_REASONS_STATUS = 451;
+
+/**
+ * Client-facing message paired with {@link UNAVAILABLE_FOR_LEGAL_REASONS_STATUS}.
+ *
+ * The upstream payload is deliberately not forwarded: it is not client-facing
+ * copy and its shape is not part of any contract this gateway relies on.
+ */
+export const UNAVAILABLE_FOR_LEGAL_REASONS_MESSAGE =
+  'Unavailable for legal reasons';

src/datasources/errors/helpers/banned-safe.helper.spec.ts

@@ -0,0 +1,77 @@
+// SPDX-License-Identifier: FSL-1.1-MIT
+import { faker } from '@faker-js/faker';
+import {
+  UNAVAILABLE_FOR_LEGAL_REASONS_MESSAGE,
+  UNAVAILABLE_FOR_LEGAL_REASONS_STATUS,
+} from '@/datasources/errors/constants';
+import { mapBannedSafeError } from '@/datasources/errors/helpers/banned-safe.helper';
+import { HttpErrorFactory } from '@/datasources/errors/http-error-factory';
+import {
+  NetworkRequestError,
+  NetworkResponseError,
+} from '@/datasources/network/entities/network.error.entity';
+
+describe('mapBannedSafeError', () => {
+  it('replaces the payload of a banned-Safe response with a client-facing message', () => {
+    const error = new NetworkResponseError(
+      new URL(faker.internet.url()),
+      {
+        status: UNAVAILABLE_FOR_LEGAL_REASONS_STATUS,
+      } as Response,
+      // The Transaction Service reports the reason under `detail`
+      { detail: 'Safe is unavailable for legal reasons' },
+    );
+
+    const actual = mapBannedSafeError(error);
+
+    expect(actual).toBeInstanceOf(NetworkResponseError);
+    expect(actual).toMatchObject({
+      url: error.url,
+      response: error.response,
+      data: { message: UNAVAILABLE_FOR_LEGAL_REASONS_MESSAGE },
+    });
+  });
+
+  it('returns a response error of any other status untouched', () => {
+    let statusCode: number;
+    do {
+      statusCode = faker.internet.httpStatusCode({
+        types: ['clientError', 'serverError'],
+      });
+    } while (statusCode === UNAVAILABLE_FOR_LEGAL_REASONS_STATUS);
+    const error = new NetworkResponseError(
+      new URL(faker.internet.url()),
+      { status: statusCode } as Response,
+      { message: faker.word.words() },
+    );
+
+    expect(mapBannedSafeError(error)).toBe(error);
+  });
+
+  it('returns a request error untouched', () => {
+    const error = new NetworkRequestError(new URL(faker.internet.url()));
+
+    expect(mapBannedSafeError(error)).toBe(error);
+  });
+
+  it('returns an arbitrary error untouched', () => {
+    const error = new Error(faker.word.words());
+
+    expect(mapBannedSafeError(error)).toBe(error);
+  });
+
+  it('yields a 451 DataSourceError once funneled through HttpErrorFactory', () => {
+    const error = new NetworkResponseError(
+      new URL(faker.internet.url()),
+      {
+        status: UNAVAILABLE_FOR_LEGAL_REASONS_STATUS,
+      } as Response,
+      { detail: 'Safe is unavailable for legal reasons' },
+    );
+
+    const actual = new HttpErrorFactory().from(mapBannedSafeError(error));
+
+    expect(actual.code).toBe(UNAVAILABLE_FOR_LEGAL_REASONS_STATUS);
+    expect(actual.message).toBe(UNAVAILABLE_FOR_LEGAL_REASONS_MESSAGE);
+  });
+});

src/datasources/errors/helpers/banned-safe.helper.ts

@@ -0,0 +1,32 @@
+// SPDX-License-Identifier: FSL-1.1-MIT
+import {
+  UNAVAILABLE_FOR_LEGAL_REASONS_MESSAGE,
+  UNAVAILABLE_FOR_LEGAL_REASONS_STATUS,
+} from '@/datasources/errors/constants';
+import { NetworkResponseError } from '@/datasources/network/entities/network.error.entity';
+
+/**
+ * Rewrites the payload of a banned-Safe response so that `HttpErrorFactory`
+ * forwards a client-facing message alongside its status.
+ *
+ * The Transaction Service answers every Safe-scoped endpoint with
+ * {@link UNAVAILABLE_FOR_LEGAL_REASONS_STATUS} when the Safe is banned from
+ * the indexer for legal reasons, reporting the reason under `detail`.
+ * `HttpErrorFactory` only reads `message`, so without this the client would
+ * receive the status alongside a generic message.
+ *
+ * Any other error is returned untouched.
+ *
+ * @see https://github.com/safe-global/safe-transaction-service/pull/2966
+ */
+export function mapBannedSafeError(error: unknown): unknown {
+  if (
+    error instanceof NetworkResponseError &&
+    error.response.status === UNAVAILABLE_FOR_LEGAL_REASONS_STATUS
+  ) {
+    return new NetworkResponseError(error.url, error.response, {
+      message: UNAVAILABLE_FOR_LEGAL_REASONS_MESSAGE,
+    });
+  }
+  return error;
+}

src/modules/balances/datasources/safe-balances-api.service.ts

@@ -6,6 +6,7 @@ import type { IConfigurationService } from '@/config/configuration.service.inter
 import type { CacheFirstDataSource } from '@/datasources/cache/cache.first.data.source';
 import { CacheRouter } from '@/datasources/cache/cache.router';
 import type { ICacheService } from '@/datasources/cache/cache.service.interface';
+import { mapBannedSafeError } from '@/datasources/errors/helpers/banned-safe.helper';
 import { HttpErrorFactory } from '@/datasources/errors/http-error-factory';
 import type { INetworkService } from '@/datasources/network/network.service.interface';
 import { getNumberString } from '@/domain/common/utils/utils';
@@ -105,7 +106,7 @@ export class SafeBalancesApi implements IBalancesApi {
       if (error instanceof ZodError) {
         throw error;
       }
-      throw this.httpErrorFactory.from(error);
+      throw this.httpErrorFactory.from(mapBannedSafeError(error));
     }
   }
 
@@ -177,7 +178,7 @@ export class SafeBalancesApi implements IBalancesApi {
       if (error instanceof ZodError) {
         throw error;
       }
-      throw this.httpErrorFactory.from(error);
+      throw this.httpErrorFactory.from(mapBannedSafeError(error));
     }
   }
 
@@ -217,7 +218,7 @@ export class SafeBalancesApi implements IBalancesApi {
         expireTimeSeconds: this.defaultExpirationTimeInSeconds,
       });
     } catch (error) {
-      throw this.httpErrorFactory.from(error);
+      throw this.httpErrorFactory.from(mapBannedSafeError(error));
     }
   }
 

src/modules/balances/routes/balances.controller.integration.spec.ts

@@ -13,6 +13,10 @@ import {
 import { createTestModule } from '@/__tests__/testing-module';
 import { IConfigurationService } from '@/config/configuration.service.interface';
 import configuration from '@/config/entities/__tests__/configuration';
+import {
+  UNAVAILABLE_FOR_LEGAL_REASONS_MESSAGE,
+  UNAVAILABLE_FOR_LEGAL_REASONS_STATUS,
+} from '@/datasources/errors/constants';
 import { NetworkResponseError } from '@/datasources/network/entities/network.error.entity';
 import type { INetworkService } from '@/datasources/network/network.service.interface';
 import { NetworkService } from '@/datasources/network/network.service.interface';
@@ -830,6 +834,43 @@ describe('Balances Controller', () => {
 
         expect(networkService.get.mock.calls.length).toBe(2);
       });
+
+      it(`451 error response for a banned Safe`, async () => {
+        const chainId = '1';
+        const safeAddress = getAddress(faker.finance.ethereumAddress());
+        const chainResponse = chainBuilder().with('chainId', chainId).build();
+        const transactionServiceUrl = `${chainResponse.transactionService}/api/v1/safes/${safeAddress}/balances/`;
+        networkService.get.mockImplementation(({ url }) => {
+          if (url === `${safeConfigUrl}/api/v1/chains/${chainId}`) {
+            return Promise.resolve({
+              data: rawify(chainResponse),
+              status: 200,
+            });
+          }
+          if (url === transactionServiceUrl) {
+            const error = new NetworkResponseError(
+              new URL(transactionServiceUrl),
+              {
+                status: UNAVAILABLE_FOR_LEGAL_REASONS_STATUS,
+              } as Response,
+              // The Transaction Service reports the reason under `detail`
+              { detail: 'Safe is unavailable for legal reasons' },
+            );
+            return Promise.reject(error);
+          }
+          return Promise.reject(new Error(`Could not match ${url}`));
+        });
+
+        await request(app.getHttpServer())
+          .get(`/v1/chains/${chainId}/safes/${safeAddress}/balances/usd`)
+          .expect(UNAVAILABLE_FOR_LEGAL_REASONS_STATUS)
+          .expect({
+            message: UNAVAILABLE_FOR_LEGAL_REASONS_MESSAGE,
+            code: UNAVAILABLE_FOR_LEGAL_REASONS_STATUS,
+          });
+
+        expect(networkService.get.mock.calls.length).toBe(2);
+      });
     });
 
     it(`502 error if validation fails`, async () => {

src/modules/csv-export/v1/datasources/export-api.service.spec.ts

@@ -5,6 +5,7 @@ import { getAddress } from 'viem';
 import type { MockedObject } from 'vitest';
 import type { IConfigurationService } from '@/config/configuration.service.interface';
 import type { CacheFirstDataSource } from '@/datasources/cache/cache.first.data.source';
+import { UNAVAILABLE_FOR_LEGAL_REASONS_STATUS } from '@/datasources/errors/constants';
 import { HttpErrorFactory } from '@/datasources/errors/http-error-factory';
 import { NetworkResponseError } from '@/datasources/network/entities/network.error.entity';
 import { pageBuilder } from '@/domain/entities/__tests__/page.builder';
@@ -139,9 +140,13 @@ describe('ExportApi', () => {
       const executionDateLte = faker.date.recent().toISOString();
 
       const errorMessage = faker.word.words();
-      const statusCode = faker.internet.httpStatusCode({
-        types: ['clientError', 'serverError'],
-      });
+      // 451 is mapped to a dedicated banned-Safe message
+      let statusCode: number;
+      do {
+        statusCode = faker.internet.httpStatusCode({
+          types: ['clientError', 'serverError'],
+        });
+      } while (statusCode === UNAVAILABLE_FOR_LEGAL_REASONS_STATUS);
 
       const exportUrl = `${baseUrl}/api/v1/safes/${safeAddress}/export/`;
       mockCacheFirstDataSource.get.mockImplementation(({ url }) => {

src/modules/csv-export/v1/datasources/export-api.service.ts

@@ -4,6 +4,7 @@ import type { Address } from 'viem';
 import { IConfigurationService } from '@/config/configuration.service.interface';
 import type { CacheFirstDataSource } from '@/datasources/cache/cache.first.data.source';
 import { CacheRouter } from '@/datasources/cache/cache.router';
+import { mapBannedSafeError } from '@/datasources/errors/helpers/banned-safe.helper';
 import { HttpErrorFactory } from '@/datasources/errors/http-error-factory';
 import type { Page } from '@/domain/entities/page.entity';
 import type { IExportApi } from '@/modules/csv-export/v1/datasources/export-api.interface';
@@ -60,7 +61,7 @@ export class ExportApi implements IExportApi {
         notFoundExpireTimeSeconds: this.defaultNotFoundExpirationTimeSeconds,
       });
     } catch (error) {
-      throw this.httpErrorFactory.from(error);
+      throw this.httpErrorFactory.from(mapBannedSafeError(error));
     }
   }
 }

src/modules/safe/routes/safes.controller.integration.spec.ts

@@ -12,6 +12,11 @@ import {
 } from '@/__tests__/test-app.provider';
 import { createTestModule } from '@/__tests__/testing-module';
 import { IConfigurationService } from '@/config/configuration.service.interface';
+import {
+  UNAVAILABLE_FOR_LEGAL_REASONS_MESSAGE,
+  UNAVAILABLE_FOR_LEGAL_REASONS_STATUS,
+} from '@/datasources/errors/constants';
+import { NetworkResponseError } from '@/datasources/network/entities/network.error.entity';
 import type { INetworkService } from '@/datasources/network/network.service.interface';
 import { NetworkService } from '@/datasources/network/network.service.interface';
 import { pageBuilder } from '@/domain/entities/__tests__/page.builder';
@@ -2395,4 +2400,42 @@ describe('Safes Controller', () => {
         }),
       );
   });
+
+  it('returns 451 when the Transaction Service reports the Safe as banned', async () => {
+    const chain = chainBuilder().build();
+    const safeAddress = getAddress(faker.finance.ethereumAddress());
+    const safeUrl = `${chain.transactionService}/api/v1/safes/${safeAddress}`;
+
+    networkService.get.mockImplementation(({ url }) => {
+      switch (url) {
+        case `${safeConfigUrl}/api/v1/chains/${chain.chainId}`:
+          return Promise.resolve({ data: rawify(chain), status: 200 });
+        case `${chain.transactionService}/api/v1/about/singletons/`:
+          return Promise.resolve({
+            data: rawify([singletonBuilder().build()]),
+            status: 200,
+          });
+        case safeUrl:
+          return Promise.reject(
+            new NetworkResponseError(
+              new URL(safeUrl),
+              {
+                status: UNAVAILABLE_FOR_LEGAL_REASONS_STATUS,
+              } as Response,
+              // The Transaction Service reports the reason under `detail`
+              { detail: 'Safe is unavailable for legal reasons' },
+            ),
+          );
+      }
+      return Promise.reject(`No matching rule for url: ${url}`);
+    });
+
+    await request(app.getHttpServer())
+      .get(`/v1/chains/${chain.chainId}/safes/${safeAddress}`)
+      .expect(UNAVAILABLE_FOR_LEGAL_REASONS_STATUS)
+      .expect({
+        code: UNAVAILABLE_FOR_LEGAL_REASONS_STATUS,
+        message: UNAVAILABLE_FOR_LEGAL_REASONS_MESSAGE,
+      });
+  });
 });