fix: extract clean error messages from API responses

clavery · clavery · commit db6b4ad5ae1b · 2026-01-21T14:52:18.000-05:00
When API requests fail with non-JSON responses (like HTML error pages),
error messages now show the HTTP status code (e.g., "HTTP 521 Web Server
Is Down") instead of serializing the entire response body.

Added getApiErrorMessage(error, response) utility that extracts clean
error messages from ODS, OCAPI, and SCAPI error patterns with HTTP
status fallback.
diff --git a/.changeset/fix-error-output.md b/.changeset/fix-error-output.md
@@ -0,0 +1,8 @@
+---
+'@salesforce/b2c-cli': patch
+'@salesforce/b2c-tooling-sdk': patch
+---
+
+Fix HTML response bodies appearing in ERROR log lines. When API requests fail with non-JSON responses (like HTML error pages), error messages now show the HTTP status code (e.g., "HTTP 521 Web Server Is Down") instead of serializing the entire response body.
+
+Added `getApiErrorMessage(error, response)` utility that extracts clean error messages from ODS, OCAPI, and SCAPI error patterns with HTTP status fallback.
diff --git a/packages/b2c-cli/src/commands/ods/create.ts b/packages/b2c-cli/src/commands/ods/create.ts
@@ -6,7 +6,7 @@
 import {Flags, ux} from '@oclif/core';
 import cliui from 'cliui';
 import {OdsCommand} from '@salesforce/b2c-tooling-sdk/cli';
-import type {OdsComponents} from '@salesforce/b2c-tooling-sdk';
+import {getApiErrorMessage, type OdsComponents} from '@salesforce/b2c-tooling-sdk';
 import {t} from '../../i18n/index.js';
 
 type SandboxModel = OdsComponents['schemas']['SandboxModel'];
@@ -139,11 +139,9 @@ export default class OdsCreate extends OdsCommand<typeof OdsCreate> {
     });
 
     if (!result.data?.data) {
-      const errorResponse = result.error as OdsComponents['schemas']['ErrorResponse'] | undefined;
-      const errorMessage = errorResponse?.error?.message || result.response?.statusText || 'Unknown error';
       this.error(
         t('commands.ods.create.error', 'Failed to create sandbox: {{message}}', {
-          message: errorMessage,
+          message: getApiErrorMessage(result.error, result.response),
         }),
       );
     }
diff --git a/packages/b2c-cli/src/commands/ods/delete.ts b/packages/b2c-cli/src/commands/ods/delete.ts
@@ -6,7 +6,7 @@
 import * as readline from 'node:readline';
 import {Args, Flags} from '@oclif/core';
 import {OdsCommand} from '@salesforce/b2c-tooling-sdk/cli';
-import type {OdsComponents} from '@salesforce/b2c-tooling-sdk';
+import {getApiErrorMessage} from '@salesforce/b2c-tooling-sdk';
 import {t} from '../../i18n/index.js';
 
 /**
@@ -92,11 +92,9 @@ export default class OdsDelete extends OdsCommand<typeof OdsDelete> {
     });
 
     if (result.response.status !== 202) {
-      const errorResponse = result.error as OdsComponents['schemas']['ErrorResponse'] | undefined;
-      const errorMessage = errorResponse?.error?.message || result.response?.statusText || 'Unknown error';
       this.error(
         t('commands.ods.delete.error', 'Failed to delete sandbox: {{message}}', {
-          message: errorMessage,
+          message: getApiErrorMessage(result.error, result.response),
         }),
       );
     }
diff --git a/packages/b2c-cli/src/commands/ods/list.ts b/packages/b2c-cli/src/commands/ods/list.ts
@@ -5,7 +5,7 @@
  */
 import {Flags} from '@oclif/core';
 import {OdsCommand, TableRenderer, type ColumnDef} from '@salesforce/b2c-tooling-sdk/cli';
-import type {OdsComponents} from '@salesforce/b2c-tooling-sdk';
+import {getApiErrorMessage, type OdsComponents} from '@salesforce/b2c-tooling-sdk';
 import {t} from '../../i18n/index.js';
 
 type SandboxModel = OdsComponents['schemas']['SandboxModel'];
@@ -142,11 +142,9 @@ export default class OdsList extends OdsCommand<typeof OdsList> {
     });
 
     if (result.error) {
-      const errorResponse = result.error as OdsComponents['schemas']['ErrorResponse'] | undefined;
-      const errorMessage = errorResponse?.error?.message || result.response?.statusText || 'Unknown error';
       this.error(
         t('commands.ods.list.error', 'Failed to fetch sandboxes: {{message}}', {
-          message: errorMessage,
+          message: getApiErrorMessage(result.error, result.response),
         }),
       );
     }
diff --git a/packages/b2c-cli/src/commands/ods/restart.ts b/packages/b2c-cli/src/commands/ods/restart.ts
@@ -5,7 +5,7 @@
  */
 import {Args} from '@oclif/core';
 import {OdsCommand} from '@salesforce/b2c-tooling-sdk/cli';
-import type {OdsComponents} from '@salesforce/b2c-tooling-sdk';
+import {getApiErrorMessage, type OdsComponents} from '@salesforce/b2c-tooling-sdk';
 import {t} from '../../i18n/index.js';
 
 type SandboxOperationModel = OdsComponents['schemas']['SandboxOperationModel'];
@@ -45,11 +45,9 @@ export default class OdsRestart extends OdsCommand<typeof OdsRestart> {
     });
 
     if (!result.data?.data) {
-      const errorResponse = result.error as OdsComponents['schemas']['ErrorResponse'] | undefined;
-      const errorMessage = errorResponse?.error?.message || result.response?.statusText || 'Unknown error';
       this.error(
         t('commands.ods.restart.error', 'Failed to restart sandbox: {{message}}', {
-          message: errorMessage,
+          message: getApiErrorMessage(result.error, result.response),
         }),
       );
     }
diff --git a/packages/b2c-cli/src/commands/ods/start.ts b/packages/b2c-cli/src/commands/ods/start.ts
@@ -5,7 +5,7 @@
  */
 import {Args} from '@oclif/core';
 import {OdsCommand} from '@salesforce/b2c-tooling-sdk/cli';
-import type {OdsComponents} from '@salesforce/b2c-tooling-sdk';
+import {getApiErrorMessage, type OdsComponents} from '@salesforce/b2c-tooling-sdk';
 import {t} from '../../i18n/index.js';
 
 type SandboxOperationModel = OdsComponents['schemas']['SandboxOperationModel'];
@@ -45,11 +45,9 @@ export default class OdsStart extends OdsCommand<typeof OdsStart> {
     });
 
     if (!result.data?.data) {
-      const errorResponse = result.error as OdsComponents['schemas']['ErrorResponse'] | undefined;
-      const errorMessage = errorResponse?.error?.message || result.response?.statusText || 'Unknown error';
       this.error(
         t('commands.ods.start.error', 'Failed to start sandbox: {{message}}', {
-          message: errorMessage,
+          message: getApiErrorMessage(result.error, result.response),
         }),
       );
     }
diff --git a/packages/b2c-cli/src/commands/ods/stop.ts b/packages/b2c-cli/src/commands/ods/stop.ts
@@ -5,7 +5,7 @@
  */
 import {Args} from '@oclif/core';
 import {OdsCommand} from '@salesforce/b2c-tooling-sdk/cli';
-import type {OdsComponents} from '@salesforce/b2c-tooling-sdk';
+import {getApiErrorMessage, type OdsComponents} from '@salesforce/b2c-tooling-sdk';
 import {t} from '../../i18n/index.js';
 
 type SandboxOperationModel = OdsComponents['schemas']['SandboxOperationModel'];
@@ -45,11 +45,9 @@ export default class OdsStop extends OdsCommand<typeof OdsStop> {
     });
 
     if (!result.data?.data) {
-      const errorResponse = result.error as OdsComponents['schemas']['ErrorResponse'] | undefined;
-      const errorMessage = errorResponse?.error?.message || result.response?.statusText || 'Unknown error';
       this.error(
         t('commands.ods.stop.error', 'Failed to stop sandbox: {{message}}', {
-          message: errorMessage,
+          message: getApiErrorMessage(result.error, result.response),
         }),
       );
     }
diff --git a/packages/b2c-cli/src/commands/scapi/custom/status.ts b/packages/b2c-cli/src/commands/scapi/custom/status.ts
@@ -5,7 +5,12 @@
  */
 import {Command, Flags, ux} from '@oclif/core';
 import {OAuthCommand, TableRenderer, type ColumnDef} from '@salesforce/b2c-tooling-sdk/cli';
-import {createCustomApisClient, toOrganizationId, type CustomApisComponents} from '@salesforce/b2c-tooling-sdk';
+import {
+  createCustomApisClient,
+  getApiErrorMessage,
+  toOrganizationId,
+  type CustomApisComponents,
+} from '@salesforce/b2c-tooling-sdk';
 import {t} from '../../../i18n/index.js';
 
 type CustomApiEndpoint = CustomApisComponents['schemas']['CustomApiEndpoint'];
@@ -242,7 +247,11 @@ export default class ScapiCustomStatus extends ScapiCustomCommand<typeof ScapiCu
     // Ensure organizationId has the required f_ecom_ prefix
     const organizationId = toOrganizationId(tenantId);
 
-    const {data, error} = await client.GET('/organizations/{organizationId}/endpoints', {
+    const {
+      data,
+      error,
+      response: httpResponse,
+    } = await client.GET('/organizations/{organizationId}/endpoints', {
       params: {
         path: {organizationId},
         query: status ? {status: status as 'active' | 'not_registered'} : undefined,
@@ -252,7 +261,7 @@ export default class ScapiCustomStatus extends ScapiCustomCommand<typeof ScapiCu
     if (error) {
       this.error(
         t('commands.scapi.custom.status.error', 'Failed to fetch Custom API endpoints: {{message}}', {
-          message: typeof error === 'object' ? JSON.stringify(error) : String(error),
+          message: getApiErrorMessage(error, httpResponse),
         }),
       );
     }
diff --git a/packages/b2c-cli/src/commands/scapi/schemas/get.ts b/packages/b2c-cli/src/commands/scapi/schemas/get.ts
@@ -168,7 +168,7 @@ export default class ScapiSchemasGet extends ScapiSchemasCommand<typeof ScapiSch
 
     const client = this.getSchemasClient();
 
-    const {data, error} = await client.GET(
+    const {data, error, response} = await client.GET(
       '/organizations/{organizationId}/schemas/{apiFamily}/{apiName}/{apiVersion}',
       {
         params: {
@@ -186,7 +186,7 @@ export default class ScapiSchemasGet extends ScapiSchemasCommand<typeof ScapiSch
     if (error) {
       this.error(
         t('commands.scapi.schemas.get.error', 'Failed to fetch schema: {{message}}', {
-          message: formatApiError(error),
+          message: formatApiError(error, response),
         }),
       );
     }
diff --git a/packages/b2c-cli/src/commands/scapi/schemas/list.ts b/packages/b2c-cli/src/commands/scapi/schemas/list.ts
@@ -106,7 +106,7 @@ export default class ScapiSchemasList extends ScapiSchemasCommand<typeof ScapiSc
 
     const client = this.getSchemasClient();
 
-    const {data, error} = await client.GET('/organizations/{organizationId}/schemas', {
+    const {data, error, response} = await client.GET('/organizations/{organizationId}/schemas', {
       params: {
         path: {organizationId: this.getOrganizationId()},
         query: {
@@ -121,7 +121,7 @@ export default class ScapiSchemasList extends ScapiSchemasCommand<typeof ScapiSc
     if (error) {
       this.error(
         t('commands.scapi.schemas.list.error', 'Failed to fetch SCAPI schemas: {{message}}', {
-          message: formatApiError(error),
+          message: formatApiError(error, response),
         }),
       );
     }
diff --git a/packages/b2c-cli/src/commands/sites/list.ts b/packages/b2c-cli/src/commands/sites/list.ts
@@ -5,6 +5,7 @@
  */
 import {ux} from '@oclif/core';
 import {InstanceCommand, createTable, type ColumnDef} from '@salesforce/b2c-tooling-sdk/cli';
+import {getApiErrorMessage} from '@salesforce/b2c-tooling-sdk/clients';
 import type {OcapiComponents} from '@salesforce/b2c-tooling-sdk';
 import {t} from '../../i18n/index.js';
 
@@ -46,12 +47,16 @@ export default class SitesList extends InstanceCommand<typeof SitesList> {
 
     this.log(t('commands.sites.list.fetching', 'Fetching sites from {{hostname}}...', {hostname}));
 
-    const {data, error} = await this.instance.ocapi.GET('/sites', {
+    const {data, error, response} = await this.instance.ocapi.GET('/sites', {
       params: {query: {select: '(**)'}},
     });
 
     if (error) {
-      this.error(t('commands.sites.list.error', 'Failed to fetch sites: {{message}}', {message: String(error)}));
+      this.error(
+        t('commands.sites.list.error', 'Failed to fetch sites: {{message}}', {
+          message: getApiErrorMessage(error, response),
+        }),
+      );
     }
 
     const sites = data as Sites;
diff --git a/packages/b2c-cli/src/commands/slas/client/create.ts b/packages/b2c-cli/src/commands/slas/client/create.ts
@@ -178,7 +178,7 @@ export default class SlasClientCreate extends SlasClientCommand<typeof SlasClien
     if (error) {
       this.error(
         t('commands.slas.client.create.error', 'Failed to create/update SLAS client: {{message}}', {
-          message: formatApiError(error),
+          message: formatApiError(error, response),
         }),
       );
     }
diff --git a/packages/b2c-cli/src/commands/slas/client/delete.ts b/packages/b2c-cli/src/commands/slas/client/delete.ts
@@ -45,7 +45,7 @@ export default class SlasClientDelete extends SlasClientCommand<typeof SlasClien
 
     const slasClient = this.getSlasClient();
 
-    const {error} = await slasClient.DELETE('/tenants/{tenantId}/clients/{clientId}', {
+    const {error, response} = await slasClient.DELETE('/tenants/{tenantId}/clients/{clientId}', {
       params: {
         path: {tenantId, clientId},
       },
@@ -54,7 +54,7 @@ export default class SlasClientDelete extends SlasClientCommand<typeof SlasClien
     if (error) {
       this.error(
         t('commands.slas.client.delete.error', 'Failed to delete SLAS client: {{message}}', {
-          message: formatApiError(error),
+          message: formatApiError(error, response),
         }),
       );
     }
diff --git a/packages/b2c-cli/src/commands/slas/client/get.ts b/packages/b2c-cli/src/commands/slas/client/get.ts
@@ -47,7 +47,7 @@ export default class SlasClientGet extends SlasClientCommand<typeof SlasClientGe
 
     const slasClient = this.getSlasClient();
 
-    const {data, error} = await slasClient.GET('/tenants/{tenantId}/clients/{clientId}', {
+    const {data, error, response} = await slasClient.GET('/tenants/{tenantId}/clients/{clientId}', {
       params: {
         path: {tenantId, clientId},
       },
@@ -56,7 +56,7 @@ export default class SlasClientGet extends SlasClientCommand<typeof SlasClientGe
     if (error) {
       this.error(
         t('commands.slas.client.get.error', 'Failed to get SLAS client: {{message}}', {
-          message: formatApiError(error),
+          message: formatApiError(error, response),
         }),
       );
     }
diff --git a/packages/b2c-cli/src/commands/slas/client/list.ts b/packages/b2c-cli/src/commands/slas/client/list.ts
@@ -59,7 +59,7 @@ export default class SlasClientList extends SlasClientCommand<typeof SlasClientL
 
     const slasClient = this.getSlasClient();
 
-    const {data, error} = await slasClient.GET('/tenants/{tenantId}/clients', {
+    const {data, error, response} = await slasClient.GET('/tenants/{tenantId}/clients', {
       params: {
         path: {tenantId},
       },
@@ -68,7 +68,7 @@ export default class SlasClientList extends SlasClientCommand<typeof SlasClientL
     if (error) {
       this.error(
         t('commands.slas.client.list.error', 'Failed to list SLAS clients: {{message}}', {
-          message: formatApiError(error),
+          message: formatApiError(error, response),
         }),
       );
     }
diff --git a/packages/b2c-cli/src/commands/slas/client/update.ts b/packages/b2c-cli/src/commands/slas/client/update.ts
@@ -95,7 +95,11 @@ export default class SlasClientUpdate extends SlasClientCommand<typeof SlasClien
     const slasClient = this.getSlasClient();
 
     // First, fetch the existing client
-    const {data: existingData, error: getError} = await slasClient.GET('/tenants/{tenantId}/clients/{clientId}', {
+    const {
+      data: existingData,
+      error: getError,
+      response: getResponse,
+    } = await slasClient.GET('/tenants/{tenantId}/clients/{clientId}', {
       params: {
         path: {tenantId, clientId},
       },
@@ -104,7 +108,7 @@ export default class SlasClientUpdate extends SlasClientCommand<typeof SlasClien
     if (getError) {
       this.error(
         t('commands.slas.client.update.fetchError', 'Failed to fetch SLAS client: {{message}}', {
-          message: formatApiError(getError),
+          message: formatApiError(getError, getResponse),
         }),
       );
     }
@@ -128,7 +132,7 @@ export default class SlasClientUpdate extends SlasClientCommand<typeof SlasClien
     });
 
     // Update the client
-    const {data, error} = await slasClient.PUT('/tenants/{tenantId}/clients/{clientId}', {
+    const {data, error, response} = await slasClient.PUT('/tenants/{tenantId}/clients/{clientId}', {
       params: {
         path: {tenantId, clientId},
       },
@@ -138,7 +142,7 @@ export default class SlasClientUpdate extends SlasClientCommand<typeof SlasClien
     if (error) {
       this.error(
         t('commands.slas.client.update.error', 'Failed to update SLAS client: {{message}}', {
-          message: formatApiError(error),
+          message: formatApiError(error, response),
         }),
       );
     }
diff --git a/packages/b2c-cli/src/utils/scapi/schemas.ts b/packages/b2c-cli/src/utils/scapi/schemas.ts
@@ -5,14 +5,19 @@
  */
 import {Command, Flags} from '@oclif/core';
 import {OAuthCommand} from '@salesforce/b2c-tooling-sdk/cli';
-import {createScapiSchemasClient, toOrganizationId, type ScapiSchemasClient} from '@salesforce/b2c-tooling-sdk/clients';
+import {
+  createScapiSchemasClient,
+  getApiErrorMessage,
+  toOrganizationId,
+  type ScapiSchemasClient,
+} from '@salesforce/b2c-tooling-sdk/clients';
 import {t} from '../../i18n/index.js';
 
 /**
  * Format API error for display.
  */
-export function formatApiError(error: unknown): string {
-  return typeof error === 'object' ? JSON.stringify(error) : String(error);
+export function formatApiError(error: unknown, response: Response): string {
+  return getApiErrorMessage(error, response);
 }
 
 /**
diff --git a/packages/b2c-cli/src/utils/slas/client.ts b/packages/b2c-cli/src/utils/slas/client.ts
diff --git a/packages/b2c-tooling-sdk/src/clients/error-utils.ts b/packages/b2c-tooling-sdk/src/clients/error-utils.ts
diff --git a/packages/b2c-tooling-sdk/src/clients/index.ts b/packages/b2c-tooling-sdk/src/clients/index.ts
diff --git a/packages/b2c-tooling-sdk/src/index.ts b/packages/b2c-tooling-sdk/src/index.ts
diff --git a/packages/b2c-tooling-sdk/test/clients/error-utils.test.ts b/packages/b2c-tooling-sdk/test/clients/error-utils.test.ts
