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

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):