feat(feedback): allow error messages to be customized

Adds five new text options (errorEmptyMessageText, errorNoClientText,
errorTimeoutText, errorForbiddenText, errorGenericText) to
FeedbackTextConfiguration so consumers can translate or reword the
widget's error messages. sendFeedback now throws/rejects with stable
codes (typed via FeedbackErrorCode) and the widget maps those codes
to the configured text.

Closes #14687

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: logaretm

packages/core/src/types-hoist/feedback/config.ts

@@ -191,6 +191,31 @@ export interface FeedbackTextConfiguration {
    * The label for the button that removed a highlight/hidden section of the screenshot.
    */
   removeHighlightText: string;
+
+  /**
+   * Error text shown when feedback submission is attempted with an empty message
+   */
+  errorEmptyMessageText: string;
+
+  /**
+   * Error text shown when the Sentry client is not set up
+   */
+  errorNoClientText: string;
+
+  /**
+   * Error text shown when the feedback submission times out (after 30s)
+   */
+  errorTimeoutText: string;
+
+  /**
+   * Error text shown when the feedback submission is blocked because the domain is not allowed (HTTP 403)
+   */
+  errorForbiddenText: string;
+
+  /**
+   * Error text shown when the feedback submission fails for any other reason (e.g. network error, ad-blocker)
+   */
+  errorGenericText: string;
 }
 
 /**

packages/feedback/src/constants/index.ts

@@ -26,6 +26,14 @@ export const HIGHLIGHT_TOOL_TEXT = 'Highlight';
 export const HIDE_TOOL_TEXT = 'Hide';
 export const REMOVE_HIGHLIGHT_TEXT = 'Remove';
 
+export const ERROR_EMPTY_MESSAGE_TEXT = 'Unable to submit feedback with empty message';
+export const ERROR_NO_CLIENT_TEXT = 'No client setup, cannot send feedback.';
+export const ERROR_TIMEOUT_TEXT = 'Unable to determine if Feedback was correctly sent.';
+export const ERROR_FORBIDDEN_TEXT =
+  'Unable to send feedback. This could be because this domain is not in your list of allowed domains.';
+export const ERROR_GENERIC_TEXT =
+  'Unable to send feedback. This could be because of network issues, or because you are using an ad-blocker.';
+
 export const FEEDBACK_WIDGET_SOURCE = 'widget';
 export const FEEDBACK_API_SOURCE = 'api';
 

packages/feedback/src/core/integration.ts

@@ -1,4 +1,5 @@
 /* eslint-disable max-lines */
+/* eslint-disable complexity */
 
 import type {
   FeedbackInternalOptions,
@@ -15,6 +16,11 @@ import {
   DOCUMENT,
   EMAIL_LABEL,
   EMAIL_PLACEHOLDER,
+  ERROR_EMPTY_MESSAGE_TEXT,
+  ERROR_FORBIDDEN_TEXT,
+  ERROR_GENERIC_TEXT,
+  ERROR_NO_CLIENT_TEXT,
+  ERROR_TIMEOUT_TEXT,
   FORM_TITLE,
   HIDE_TOOL_TEXT,
   HIGHLIGHT_TOOL_TEXT,
@@ -119,6 +125,11 @@ export const buildFeedbackIntegration = ({
     highlightToolText = HIGHLIGHT_TOOL_TEXT,
     hideToolText = HIDE_TOOL_TEXT,
     removeHighlightText = REMOVE_HIGHLIGHT_TEXT,
+    errorEmptyMessageText = ERROR_EMPTY_MESSAGE_TEXT,
+    errorNoClientText = ERROR_NO_CLIENT_TEXT,
+    errorTimeoutText = ERROR_TIMEOUT_TEXT,
+    errorForbiddenText = ERROR_FORBIDDEN_TEXT,
+    errorGenericText = ERROR_GENERIC_TEXT,
 
     // FeedbackCallbacks
     onFormOpen,
@@ -164,6 +175,11 @@ export const buildFeedbackIntegration = ({
       highlightToolText,
       hideToolText,
       removeHighlightText,
+      errorEmptyMessageText,
+      errorNoClientText,
+      errorTimeoutText,
+      errorForbiddenText,
+      errorGenericText,
 
       onFormClose,
       onFormOpen,

packages/feedback/src/core/sendFeedback.ts

@@ -1,6 +1,8 @@
 import type { Event, EventHint, SendFeedback, SendFeedbackParams, TransportMakeRequestResponse } from '@sentry/core';
 import { captureFeedback, getClient, getCurrentScope, getLocationHref } from '@sentry/core';
 import { FEEDBACK_API_SOURCE } from '../constants';
+import type { FeedbackErrorCode } from '../util/createFeedbackError';
+import { createFeedbackError } from '../util/createFeedbackError';
 
 /**
  * Public API to send a Feedback item to Sentry
@@ -10,14 +12,14 @@ export const sendFeedback: SendFeedback = (
   hint: EventHint & { includeReplay?: boolean } = { includeReplay: true },
 ): Promise<string> => {
   if (!params.message) {
-    throw new Error('Unable to submit feedback with empty message');
+    throw createFeedbackError('ERROR_EMPTY_MESSAGE');
   }
 
   // We want to wait for the feedback to be sent (or not)
   const client = getClient();
 
   if (!client) {
-    throw new Error('No client setup, cannot send feedback.');
+    throw createFeedbackError('ERROR_NO_CLIENT');
   }
 
   if (params.tags && Object.keys(params.tags).length) {
@@ -35,7 +37,7 @@ export const sendFeedback: SendFeedback = (
   // We want to wait for the feedback to be sent (or not)
   return new Promise<string>((resolve, reject) => {
     // After 30s, we want to clear anyhow
-    const timeout = setTimeout(() => reject('Unable to determine if Feedback was correctly sent.'), 30_000);
+    const timeout = setTimeout(() => reject('ERROR_TIMEOUT' satisfies FeedbackErrorCode), 30_000);
 
     const cleanup = client.on('afterSendEvent', (event: Event, response: TransportMakeRequestResponse) => {
       if (event.event_id !== eventId) {
@@ -51,14 +53,10 @@ export const sendFeedback: SendFeedback = (
       }
 
       if (response?.statusCode === 403) {
-        return reject(
-          'Unable to send feedback. This could be because this domain is not in your list of allowed domains.',
-        );
+        return reject('ERROR_FORBIDDEN' satisfies FeedbackErrorCode);
       }
 
-      return reject(
-        'Unable to send feedback. This could be because of network issues, or because you are using an ad-blocker.',
-      );
+      return reject('ERROR_GENERIC' satisfies FeedbackErrorCode);
     });
   });
 };

packages/feedback/src/modal/components/Form.tsx

@@ -9,6 +9,7 @@ import type { JSX, VNode } from 'preact';
 import { h } from 'preact'; // eslint-disable-line @typescript-eslint/no-unused-vars
 import { useCallback, useState } from 'preact/hooks';
 import { FEEDBACK_WIDGET_SOURCE } from '../../constants';
+import type { FeedbackErrorCode } from '../../util/createFeedbackError';
 import { DEBUG_BUILD } from '../../util/debug-build';
 import { getMissingFields } from '../../util/validate';
 
@@ -59,7 +60,20 @@ export function Form({
     namePlaceholder,
     submitButtonLabel,
     isRequiredLabel,
+    errorEmptyMessageText,
+    errorNoClientText,
+    errorTimeoutText,
+    errorForbiddenText,
+    errorGenericText,
   } = options;
+
+  const errorTextByCode: Record<FeedbackErrorCode, string> = {
+    ERROR_EMPTY_MESSAGE: errorEmptyMessageText,
+    ERROR_NO_CLIENT: errorNoClientText,
+    ERROR_TIMEOUT: errorTimeoutText,
+    ERROR_FORBIDDEN: errorForbiddenText,
+    ERROR_GENERIC: errorGenericText,
+  };
   const [isSubmitting, setIsSubmitting] = useState<boolean>(false);
   // TODO: set a ref on the form, and whenever an input changes call processForm() and setError()
   const [error, setError] = useState<null | string>(null);
@@ -131,8 +145,9 @@ export function Form({
           onSubmitSuccess(data, eventId);
         } catch (error) {
           DEBUG_BUILD && debug.error(error);
-          setError(error as string);
-          onSubmitError(error as Error);
+          const err = error instanceof Error ? error : new Error(String(error));
+          setError(errorTextByCode[err.message as FeedbackErrorCode] || errorGenericText);
+          onSubmitError(err);
         }
       } finally {
         setIsSubmitting(false);

packages/feedback/src/util/createFeedbackError.ts

@@ -0,0 +1,10 @@
+export type FeedbackErrorCode =
+  | 'ERROR_EMPTY_MESSAGE'
+  | 'ERROR_NO_CLIENT'
+  | 'ERROR_TIMEOUT'
+  | 'ERROR_FORBIDDEN'
+  | 'ERROR_GENERIC';
+
+export function createFeedbackError(reason: FeedbackErrorCode): Error {
+  return new Error(reason);
+}

packages/feedback/test/core/sendFeedback.test.ts

@@ -279,9 +279,7 @@ describe('sendFeedback', () => {
         email: 're@example.org',
         message: 'mi',
       }),
-    ).rejects.toMatch(
-      'Unable to send feedback. This could be because of network issues, or because you are using an ad-blocker.',
-    );
+    ).rejects.toMatch('ERROR_GENERIC');
   });
 
   it('handles 0 transport error', async () => {
@@ -296,9 +294,7 @@ describe('sendFeedback', () => {
         email: 're@example.org',
         message: 'mi',
       }),
-    ).rejects.toMatch(
-      'Unable to send feedback. This could be because of network issues, or because you are using an ad-blocker.',
-    );
+    ).rejects.toMatch('ERROR_GENERIC');
   });
 
   it('handles 403 transport error', async () => {
@@ -313,9 +309,7 @@ describe('sendFeedback', () => {
         email: 're@example.org',
         message: 'mi',
       }),
-    ).rejects.toMatch(
-      'Unable to send feedback. This could be because this domain is not in your list of allowed domains.',
-    );
+    ).rejects.toMatch('ERROR_FORBIDDEN');
   });
 
   it('handles 200 transport response', async () => {
@@ -349,7 +343,7 @@ describe('sendFeedback', () => {
 
     vi.advanceTimersByTime(30_000);
 
-    await expect(promise).rejects.toMatch('Unable to determine if Feedback was correctly sent.');
+    await expect(promise).rejects.toMatch('ERROR_TIMEOUT');
 
     vi.useRealTimers();
   });