feat(seer): Return _seer_error_detail on timeseries query 400s

execute_timeseries_query previously let client.ApiError propagate on any
non-2xx response, so a malformed query surfaced as an unhandled exception
rather than actionable feedback for the query builder agent.

Catch 400s and return the error detail under a reserved _seer_error_detail
key. The key is deliberately distinct from a plain "error" key because
grouped timeseries responses are keyed by group_by value at the top level,
so an "error" group would otherwise be indistinguishable from a failure.
Non-400 errors continue to propagate.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: aliu39

src/sentry/seer/agent/tools.py

@@ -299,12 +299,26 @@ def execute_timeseries_query(
     params = {k: v for k, v in params.items() if v is not None}
 
     # Call sentry API client. This will raise API errors for non-2xx / 3xx status.
-    resp = client.get(
-        auth=ApiKey(organization_id=organization.id, scope_list=["org:read", "project:read"]),
-        user=None,
-        path=f"/organizations/{organization.slug}/events-stats/",
-        params=params,
-    )
+    try:
+        resp = client.get(
+            auth=ApiKey(organization_id=organization.id, scope_list=["org:read", "project:read"]),
+            user=None,
+            path=f"/organizations/{organization.slug}/events-stats/",
+            params=params,
+        )
+    except client.ApiError as e:
+        # For 400 errors, return an error detail for the query builder agent.
+        # Use a reserved "_seer_error_detail" key so it can't collide with a
+        # group_by value (which becomes a top-level key in grouped responses below).
+        if e.status_code == 400:
+            logger.exception("execute_timeseries_query: bad request", extra={"org_id": org_id})
+            error_detail = e.body.get("detail") if isinstance(e.body, dict) else None
+            return {
+                "_seer_error_detail": (
+                    str(error_detail) if error_detail is not None else str(e.body)
+                )
+            }
+        raise
     data = resp.data
 
     # Always normalize to the nested {"metric": {"data": [...]}} format for consistency

tests/sentry/seer/agent/test_tools.py

@@ -455,6 +455,54 @@ def test_spans_table_query_error_handling(self, mock_client_get):
 
         assert exc_info.value.status_code == 500
 
+    @patch("sentry.seer.agent.tools.client.get")
+    def test_spans_timeseries_query_error_handling(self, mock_client_get: Mock) -> None:
+        """400 errors return the detail under a reserved _seer_error_detail key so it can't collide
+        with a group_by value (which becomes a top-level key); non-400 errors are re-raised."""
+        # 400 error with dict body containing detail.
+        error_detail_msg = "Invalid query: field 'invalid_field' does not exist"
+        mock_client_get.side_effect = client.ApiError(400, {"detail": error_detail_msg})
+
+        result = execute_timeseries_query(
+            org_id=self.organization.id,
+            dataset="spans",
+            y_axes=["count()"],
+            query="invalid_field:value",
+            stats_period="1h",
+        )
+
+        assert result == {"_seer_error_detail": error_detail_msg}
+        # The detail is not exposed under "error", where it could shadow a group value.
+        assert "error" not in result
+
+        # 400 error with a non-dict body falls back to stringifying the whole body.
+        error_body = "Bad request: malformed query syntax"
+        mock_client_get.side_effect = client.ApiError(400, error_body)
+
+        result = execute_timeseries_query(
+            org_id=self.organization.id,
+            dataset="spans",
+            y_axes=["count()"],
+            query="malformed query",
+            stats_period="1h",
+        )
+
+        assert result == {"_seer_error_detail": error_body}
+
+        # Non-400 errors are re-raised.
+        mock_client_get.side_effect = client.ApiError(500, {"detail": "Internal server error"})
+
+        with pytest.raises(client.ApiError) as exc_info:
+            execute_timeseries_query(
+                org_id=self.organization.id,
+                dataset="spans",
+                y_axes=["count()"],
+                query="",
+                stats_period="1h",
+            )
+
+        assert exc_info.value.status_code == 500
+
     @patch("sentry.seer.agent.tools.client.get")
     def test_table_query_forwards_cross_event_params(self, mock_client_get: Mock) -> None:
         """Cross-event filters are forwarded to /events/ as repeated spanQuery/logQuery/metricQuery params."""