fix(issues): Replace 'Internal Error' message on Postgres query timeout errors

Handle Postgres statement timeout errors on issue search which previously displayed 'Internal Error' but
will now show more appropriate message explaining the query took too long and to possibly revise it

Closes: #80166

Author: yuvmen

src/sentry/api/utils.py

@@ -9,8 +9,10 @@
 from datetime import timedelta
 from typing import Any, Literal, overload
 
+import psycopg2.errorcodes
 import sentry_sdk
 from django.conf import settings
+from django.db.utils import OperationalError
 from django.http import HttpRequest
 from django.utils import timezone
 from rest_framework.exceptions import APIException, ParseError, Throttled
@@ -423,6 +425,15 @@ def handle_query_errors() -> Generator[None]:
         else:
             sentry_sdk.capture_exception(error)
         raise APIException(detail=message)
+    except OperationalError as error:
+        if hasattr(error, "pgcode") and error.pgcode == psycopg2.errorcodes.QUERY_CANCELED:
+            if options.get("api.postgres-query-timeout-error-handling.enabled"):
+                sentry_sdk.set_tag("query.error_reason", "Postgres statement timeout")
+                raise Throttled(
+                    detail="Query timeout. Please try with a smaller date range or fewer conditions."
+                )
+        # Let other OperationalErrors propagate as normal
+        raise
 
 
 def update_snuba_params_with_timestamp(

src/sentry/options/defaults.py

@@ -2773,6 +2773,14 @@
     flags=FLAG_ALLOW_EMPTY | FLAG_AUTOMATOR_MODIFIABLE,
 )
 
+# Killswitch for Postgres query timeout error handling
+register(
+    "api.postgres-query-timeout-error-handling.enabled",
+    default=False,
+    type=Bool,
+    flags=FLAG_MODIFIABLE_BOOL | FLAG_AUTOMATOR_MODIFIABLE,
+)
+
 # TODO: remove once removed from options
 register(
     "issue_platform.use_kafka_partition_key",

tests/sentry/api/test_utils.py

@@ -2,9 +2,11 @@
 import unittest
 from unittest.mock import MagicMock, patch
 
+import psycopg2
 import pytest
+from django.db import OperationalError
 from django.utils import timezone
-from rest_framework.exceptions import APIException
+from rest_framework.exceptions import APIException, Throttled
 from sentry_sdk import Scope
 
 from sentry.api.utils import (
@@ -17,6 +19,7 @@
 from sentry.exceptions import IncompatibleMetricsQuery, InvalidParams, InvalidSearchQuery
 from sentry.testutils.cases import APITestCase
 from sentry.testutils.helpers.datetime import freeze_time
+from sentry.testutils.helpers.options import override_options
 from sentry.utils.snuba import (
     DatasetSelectionError,
     QueryConnectionFailed,
@@ -168,13 +171,12 @@ class FooBarError(Exception):
     pass
 
 
-class HandleQueryErrorsTest:
+class HandleQueryErrorsTest(APITestCase):
     @patch("sentry.api.utils.ParseError")
     def test_handle_query_errors(self, mock_parse_error):
         exceptions = [
             DatasetSelectionError,
             IncompatibleMetricsQuery,
-            InvalidParams,
             InvalidSearchQuery,
             QueryConnectionFailed,
             QueryExecutionError,
@@ -198,6 +200,42 @@ def test_handle_query_errors(self, mock_parse_error):
             except Exception as e:
                 assert isinstance(e, (FooBarError, APIException))
 
+    def test_handle_postgres_timeout(self):
+        class TimeoutError(OperationalError):
+            pgcode = psycopg2.errorcodes.QUERY_CANCELED
+
+        # Test when option is disabled (default)
+        try:
+            with handle_query_errors():
+                raise TimeoutError()
+        except Exception as e:
+            assert isinstance(e, TimeoutError)  # Should propagate original error
+
+        # Test when option is enabled
+        with override_options({"api.postgres-query-timeout-error-handling.enabled": True}):
+            try:
+                with handle_query_errors():
+                    raise TimeoutError()
+            except Exception as e:
+                assert isinstance(e, Throttled)
+                assert (
+                    str(e)
+                    == "Query timeout. Please try with a smaller date range or fewer conditions."
+                )
+
+    @patch("sentry.api.utils.ParseError")
+    def test_handle_other_operational_error(self, mock_parse_error):
+        class OtherError(OperationalError):
+            # No pgcode attribute
+            pass
+
+        try:
+            with handle_query_errors():
+                raise OtherError()
+        except Exception as e:
+            assert isinstance(e, OtherError)  # Should propagate original error
+            mock_parse_error.assert_not_called()
+
 
 class ClampDateRangeTest(unittest.TestCase):
     def test_no_clamp_if_range_under_max(self):