SNOW-2129434: Add in-band http exception telemetry (#2414)

Author: sfc-gh-pbulawa

DESCRIPTION.md

@@ -9,6 +9,7 @@ Source code is also available at: https://github.com/snowflakedb/snowflake-conne
 # Release Notes
 - v3.16.1(TBD)
   - Added in-band OCSP exception telemetry.
+  - Added in-band HTTP exception telemetry.
 
 - v3.16.0(July 04,2025)
   - Bumped numpy dependency from <2.1.0 to <=2.2.4.

src/snowflake/connector/errorcode.py

@@ -89,3 +89,5 @@
 ER_NO_PYARROW_SNOWSQL = 255004
 ER_FAILED_TO_READ_ARROW_STREAM = 255005
 ER_NO_NUMPY = 255006
+
+ER_HTTP_GENERAL_ERROR = 290000

src/snowflake/connector/errors.py

@@ -8,6 +8,7 @@
 from logging import getLogger
 from typing import TYPE_CHECKING, Any
 
+from .errorcode import ER_HTTP_GENERAL_ERROR
 from .secret_detector import SecretDetector
 from .telemetry import TelemetryData, TelemetryField
 from .time_util import get_time_millis
@@ -374,6 +375,15 @@ class InterfaceError(Error):
     pass
 
 
+class HttpError(Error):
+    def __init__(self, **kwargs) -> None:
+        Error.__init__(
+            self,
+            errtype=TelemetryField.HTTP_EXCEPTION,
+            **kwargs,
+        )
+
+
 class DatabaseError(Error):
     """Exception for errors related to the database."""
 
@@ -439,7 +449,8 @@ def __init__(self, **kwargs) -> None:
         Error.__init__(
             self,
             msg=kwargs.get("msg") or "HTTP 500: Internal Server Error",
-            errno=kwargs.get("errno"),
+            errno=ER_HTTP_GENERAL_ERROR + kwargs.get("errno", 0),
+            errtype=TelemetryField.HTTP_EXCEPTION,
             sqlstate=kwargs.get("sqlstate"),
             sfqid=kwargs.get("sfqid"),
         )
@@ -452,7 +463,8 @@ def __init__(self, **kwargs) -> None:
         Error.__init__(
             self,
             msg=kwargs.get("msg") or "HTTP 503: Service Unavailable",
-            errno=kwargs.get("errno"),
+            errno=ER_HTTP_GENERAL_ERROR + kwargs.get("errno", 0),
+            errtype=TelemetryField.HTTP_EXCEPTION,
             sqlstate=kwargs.get("sqlstate"),
             sfqid=kwargs.get("sfqid"),
         )
@@ -465,7 +477,8 @@ def __init__(self, **kwargs) -> None:
         Error.__init__(
             self,
             msg=kwargs.get("msg") or "HTTP 504: Gateway Timeout",
-            errno=kwargs.get("errno"),
+            errno=ER_HTTP_GENERAL_ERROR + kwargs.get("errno", 0),
+            errtype=TelemetryField.HTTP_EXCEPTION,
             sqlstate=kwargs.get("sqlstate"),
             sfqid=kwargs.get("sfqid"),
         )
@@ -478,7 +491,8 @@ def __init__(self, **kwargs) -> None:
         Error.__init__(
             self,
             msg=kwargs.get("msg") or "HTTP 403: Forbidden",
-            errno=kwargs.get("errno"),
+            errno=ER_HTTP_GENERAL_ERROR + kwargs.get("errno", 0),
+            errtype=TelemetryField.HTTP_EXCEPTION,
             sqlstate=kwargs.get("sqlstate"),
             sfqid=kwargs.get("sfqid"),
         )
@@ -491,7 +505,8 @@ def __init__(self, **kwargs) -> None:
         Error.__init__(
             self,
             msg=kwargs.get("msg") or "HTTP 408: Request Timeout",
-            errno=kwargs.get("errno"),
+            errno=ER_HTTP_GENERAL_ERROR + kwargs.get("errno", 0),
+            errtype=TelemetryField.HTTP_EXCEPTION,
             sqlstate=kwargs.get("sqlstate"),
             sfqid=kwargs.get("sfqid"),
         )
@@ -504,7 +519,8 @@ def __init__(self, **kwargs) -> None:
         Error.__init__(
             self,
             msg=kwargs.get("msg") or "HTTP 400: Bad Request",
-            errno=kwargs.get("errno"),
+            errno=ER_HTTP_GENERAL_ERROR + kwargs.get("errno", 0),
+            errtype=TelemetryField.HTTP_EXCEPTION,
             sqlstate=kwargs.get("sqlstate"),
             sfqid=kwargs.get("sfqid"),
         )
@@ -517,7 +533,8 @@ def __init__(self, **kwargs) -> None:
         Error.__init__(
             self,
             msg=kwargs.get("msg") or "HTTP 502: Bad Gateway",
-            errno=kwargs.get("errno"),
+            errno=ER_HTTP_GENERAL_ERROR + kwargs.get("errno", 0),
+            errtype=TelemetryField.HTTP_EXCEPTION,
             sqlstate=kwargs.get("sqlstate"),
             sfqid=kwargs.get("sfqid"),
         )
@@ -530,7 +547,8 @@ def __init__(self, **kwargs) -> None:
         Error.__init__(
             self,
             msg=kwargs.get("msg") or "HTTP 405: Method not allowed",
-            errno=kwargs.get("errno"),
+            errno=ER_HTTP_GENERAL_ERROR + kwargs.get("errno", 0),
+            errtype=TelemetryField.HTTP_EXCEPTION,
             sqlstate=kwargs.get("sqlstate"),
             sfqid=kwargs.get("sfqid"),
         )
@@ -543,7 +561,8 @@ def __init__(self, **kwargs) -> None:
         Error.__init__(
             self,
             msg=kwargs.get("msg") or "HTTP 429: Too Many Requests",
-            errno=kwargs.get("errno"),
+            errno=ER_HTTP_GENERAL_ERROR + kwargs.get("errno", 0),
+            errtype=TelemetryField.HTTP_EXCEPTION,
             sqlstate=kwargs.get("sqlstate"),
             sfqid=kwargs.get("sfqid"),
         )
@@ -568,7 +587,8 @@ def __init__(self, **kwargs) -> None:
         Error.__init__(
             self,
             msg=kwargs.get("msg") or f"HTTP {code}",
-            errno=kwargs.get("errno"),
+            errno=ER_HTTP_GENERAL_ERROR + kwargs.get("errno", 0),
+            errtype=TelemetryField.HTTP_EXCEPTION,
             sqlstate=kwargs.get("sqlstate"),
             sfqid=kwargs.get("sfqid"),
         )

src/snowflake/connector/network.py

@@ -40,6 +40,7 @@
     IncompleteRead,
     urlencode,
     urlparse,
+    urlsplit,
 )
 from .constants import (
     _CONNECTIVITY_ERR_MSG,
@@ -65,6 +66,7 @@
     ER_FAILED_TO_CONNECT_TO_DB,
     ER_FAILED_TO_RENEW_SESSION,
     ER_FAILED_TO_REQUEST,
+    ER_HTTP_GENERAL_ERROR,
     ER_RETRYABLE_CODE,
 )
 from .errors import (
@@ -74,7 +76,7 @@
     Error,
     ForbiddenError,
     GatewayTimeoutError,
-    InterfaceError,
+    HttpError,
     InternalServerError,
     MethodNotAllowed,
     OperationalError,
@@ -236,10 +238,10 @@ def raise_failed_request_error(
     Error.errorhandler_wrapper(
         connection,
         None,
-        InterfaceError,
+        HttpError,
         {
-            "msg": f"{response.status_code} {response.reason}: {method} {url}",
-            "errno": ER_FAILED_TO_REQUEST,
+            "msg": f"{response.status_code} {response.reason}: {method} {urlsplit(url).netloc}{urlsplit(url).path}",
+            "errno": ER_HTTP_GENERAL_ERROR + response.status_code,
             "sqlstate": SQLSTATE_CONNECTION_WAS_NOT_ESTABLISHED,
         },
     )
@@ -1033,6 +1035,14 @@ def _request_exec_wrapper(
             retry_ctx.increment()
 
             reason = getattr(cause, "errno", 0)
+            if reason is None:
+                reason = 0
+            else:
+                reason = (
+                    reason - ER_HTTP_GENERAL_ERROR
+                    if reason >= ER_HTTP_GENERAL_ERROR
+                    else reason
+                )
             retry_ctx.retry_reason = reason
 
             if "Connection aborted" in repr(e) and "ECONNRESET" in repr(e):

src/snowflake/connector/telemetry.py

@@ -26,6 +26,7 @@ class TelemetryField(Enum):
     TIME_PARSING_CHUNKS = "client_time_parsing_chunks"
     SQL_EXCEPTION = "client_sql_exception"
     OCSP_EXCEPTION = "client_ocsp_exception"
+    HTTP_EXCEPTION = "client_http_exception"
     GET_PARTITIONS_USED = "client_get_partitions_used"
     EMPTY_SEQ_INTERPOLATION = "client_pyformat_empty_seq_interpolation"
     # fetch_pandas_* usage

test/integ/test_connection.py

@@ -30,7 +30,7 @@
     ER_NO_ACCOUNT_NAME,
     ER_NOT_IMPLICITY_SNOWFLAKE_DATATYPE,
 )
-from snowflake.connector.errors import Error, InterfaceError
+from snowflake.connector.errors import Error
 from snowflake.connector.network import APPLICATION_SNOWSQL, ReauthenticationRequest
 from snowflake.connector.sqlstate import SQLSTATE_FEATURE_NOT_SUPPORTED
 from snowflake.connector.telemetry import TelemetryField
@@ -54,6 +54,11 @@
 except ImportError:  # Keep olddrivertest from breaking
     ER_FAILED_PROCESSING_QMARK = 252012
 
+try:
+    from snowflake.connector.errors import HttpError
+except ImportError:
+    pass
+
 
 def test_basic(conn_testaccount):
     """Basic Connection test."""
@@ -530,7 +535,7 @@ def exe(sql):
 @pytest.mark.timeout(15)
 @pytest.mark.skipolddriver
 def test_invalid_account_timeout():
-    with pytest.raises(InterfaceError):
+    with pytest.raises(HttpError):
         snowflake.connector.connect(
             account="bogus", user="test", password="test", login_timeout=5
         )
@@ -569,7 +574,7 @@ def test_eu_connection(tmpdir):
     import os
 
     os.environ["SF_OCSP_RESPONSE_CACHE_SERVER_ENABLED"] = "true"
-    with pytest.raises(InterfaceError):
+    with pytest.raises(HttpError):
         # must reach Snowflake
         snowflake.connector.connect(
             account="testaccount1234",
@@ -593,7 +598,7 @@ def test_us_west_connection(tmpdir):
     Notes:
         Region is deprecated.
     """
-    with pytest.raises(InterfaceError):
+    with pytest.raises(HttpError):
         # must reach Snowflake
         snowflake.connector.connect(
             account="testaccount1234",

test/unit/test_connection.py

@@ -21,7 +21,7 @@
 from snowflake.connector.connection import DEFAULT_CONFIGURATION
 from snowflake.connector.errors import (
     Error,
-    InterfaceError,
+    HttpError,
     OperationalError,
     ProgrammingError,
 )
@@ -365,7 +365,7 @@ def test_invalid_backoff_policy():
         # passing a non-generator function should not work
         _ = fake_connector(backoff_policy=lambda: None)
 
-    with pytest.raises(InterfaceError):
+    with pytest.raises(HttpError):
         # passing a generator function should make it pass config and error during connection
         _ = fake_connector(backoff_policy=zero_backoff)
 

test/unit/test_network.py

@@ -7,10 +7,11 @@
 
 import pytest
 
+from snowflake.connector.errors import HttpError
 from src.snowflake.connector.network import SnowflakeRestfulJsonEncoder
 
 try:
-    from snowflake.connector import Error, InterfaceError
+    from snowflake.connector import Error
     from snowflake.connector.network import SnowflakeRestful
     from snowflake.connector.vendored.requests import HTTPError, Response
 except ImportError:
@@ -64,9 +65,9 @@ def test_fetch():
             == {}
         )
         assert rest.fetch(**default_parameters, no_retry=True) == {}
-        # if no retry is set to False, the function raises an InterfaceError
-        with pytest.raises(InterfaceError) as exc:
-            assert rest.fetch(**default_parameters, no_retry=False)
+        # if no retry is set to False, the function raises an HttpError
+        with pytest.raises(HttpError):
+            rest.fetch(**default_parameters, no_retry=False)
 
 
 @pytest.mark.parametrize(

test/unit/test_result_batch.py

@@ -8,7 +8,7 @@
 
 import pytest
 
-from snowflake.connector import DatabaseError, InterfaceError
+from snowflake.connector import DatabaseError
 from snowflake.connector.compat import (
     BAD_GATEWAY,
     BAD_REQUEST,
@@ -23,13 +23,14 @@
 )
 from snowflake.connector.errorcode import (
     ER_FAILED_TO_CONNECT_TO_DB,
-    ER_FAILED_TO_REQUEST,
+    ER_HTTP_GENERAL_ERROR,
 )
 from snowflake.connector.errors import (
     BadGatewayError,
     BadRequest,
     ForbiddenError,
     GatewayTimeoutError,
+    HttpError,
     InternalServerError,
     MethodNotAllowed,
     OtherHTTPRetryableError,
@@ -127,10 +128,10 @@ def test_non_200_response_download(status_code):
         mock_get.return_value = create_mock_response(status_code)
 
         with mock.patch("time.sleep", return_value=None):
-            with pytest.raises(InterfaceError) as ex:
+            with pytest.raises(HttpError) as ex:
                 _ = result_batch._download()
             error = ex.value
-            assert error.errno == ER_FAILED_TO_REQUEST
+            assert error.errno == ER_HTTP_GENERAL_ERROR + status_code
             assert error.sqlstate == SQLSTATE_CONNECTION_WAS_NOT_ESTABLISHED
         assert mock_get.call_count == MAX_DOWNLOAD_RETRY
 

test/unit/test_retry_network.py

@@ -29,7 +29,7 @@
     DatabaseError,
     Error,
     ForbiddenError,
-    InterfaceError,
+    HttpError,
     OperationalError,
     OtherHTTPRetryableError,
     ServiceUnavailableError,
@@ -217,7 +217,7 @@ def test_request_exec():
 
     # unauthorized
     type(request_mock).status_code = PropertyMock(return_value=UNAUTHORIZED)
-    with pytest.raises(InterfaceError):
+    with pytest.raises(HttpError):
         rest._request_exec(session=session, **default_parameters)
 
     # unauthorized with catch okta unauthorized error