tango-python 1.18.0__tar.gz → 1.18.1__tar.gz

{tango_python-1.18.0 → tango_python-1.18.1}/CHANGELOG.md

@@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.18.1] - 2026-10-19
+
+### Fixed
+
+- **API errors now carry the server's reason.** A 403 or other non-2xx response the SDK had no dedicated exception for raised `TangoAPIError("API request failed with status 403")` and threw the response body away, so a caller refused for a G2X-only shape field or a plan-gated filter couldn't tell why. The message now ends with the API's own explanation (`API request failed with status 403: G2X shape fields are not allowed for your account.`), and the parsed body is on `response_data`. Non-JSON bodies, such as a proxy's 502 page, keep the old message.
+
 ## [1.18.0] - 2026-10-19
 
 ### Added

{tango_python-1.18.0 → tango_python-1.18.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: tango-python
-Version: 1.18.0
+Version: 1.18.1
 Summary: Python SDK for the Tango API
 Project-URL: Homepage, https://github.com/makegov/tango-python
 Project-URL: Documentation, https://docs.makegov.com/tango-python

{tango_python-1.18.0 → tango_python-1.18.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "tango-python"
-version = "1.18.0"
+version = "1.18.1"
 description = "Python SDK for the Tango API"
 readme = "README.md"
 requires-python = ">=3.12"

{tango_python-1.18.0 → tango_python-1.18.1}/tango/__init__.py

@@ -62,7 +62,7 @@ from .webhooks import (
 )
 from .webhooks.receiver import Delivery, WebhookReceiver
 
-__version__ = "1.18.0"
+__version__ = "1.18.1"
 __all__ = [
     "TangoClient",
     "TangoAPIError",

{tango_python-1.18.0 → tango_python-1.18.1}/tango/client.py

@@ -75,6 +75,31 @@ from tango.shapes import (
 _COUNT_TYPE_KEY = "_tango_count_type"
 
 
+def _error_body(response: httpx.Response) -> dict[str, Any]:
+    """The JSON object an error response carries, or {} for an empty, non-JSON (a proxy's HTML page) or non-object body."""
+    try:
+        data = response.json() if response.content else {}
+    except ValueError:
+        return {}
+    return data if isinstance(data, dict) else {}
+
+
+def _error_reason(error_data: dict[str, Any]) -> str | None:
+    """The server's own explanation from an error body, e.g. why a 403 refused the request.
+
+    The API sends either ``{"detail": "..."}`` or a structured body such as a tier gate's ``{"error": "...", "code": "tier_required", ...}``, sometimes nested under ``detail``.
+    """
+    for body in (error_data, error_data.get("detail")):
+        if isinstance(body, str) and body:
+            return body
+        if isinstance(body, dict):
+            for key in ("error", "message", "detail"):
+                value = body.get(key)
+                if isinstance(value, str) and value:
+                    return value
+    return None
+
+
 class TangoClient:
     """Tango API Client"""
 
@@ -232,8 +257,13 @@ class TangoClient:
             detail = error_data.get("detail", "Rate limit exceeded")
             raise TangoRateLimitError(detail, response.status_code, error_data)
         elif not response.is_success:
+            error_data = _error_body(response)
+            reason = _error_reason(error_data)
+            message = f"API request failed with status {response.status_code}"
             raise TangoAPIError(
-                f"API request failed with status {response.status_code}", response.status_code
+                f"{message}: {reason}" if reason else message,
+                response.status_code,
+                error_data,
             )
 
     def _get(self, endpoint: str, params: dict[str, Any] | None = None) -> dict[str, Any]:

{tango_python-1.18.0 → tango_python-1.18.1}/tests/test_client.py

@@ -1572,6 +1572,63 @@ class TestErrorHandling:
         assert exc_info.value.status_code == 500
         assert "500" in str(exc_info.value)
 
+    @staticmethod
+    def _error_response(status, body=None, content=b"{}"):
+        response = Mock()
+        response.is_success = False
+        response.status_code = status
+        response.content = content
+        response.json.return_value = body
+        return response
+
+    @patch("tango.client.httpx.Client.request")
+    def test_403_carries_the_server_reason(self, mock_request):
+        body = {"detail": "G2X shape fields are not allowed for your account."}
+        mock_request.return_value = self._error_response(403, body)
+
+        with pytest.raises(TangoAPIError) as exc_info:
+            TangoClient(api_key="test-key").list_agencies()
+
+        assert (
+            str(exc_info.value)
+            == "API request failed with status 403: G2X shape fields are not allowed for your account."
+        )
+        assert exc_info.value.status_code == 403
+        assert exc_info.value.response_data == body
+
+    @pytest.mark.parametrize(
+        "body",
+        [
+            {"error": "The 'psc' filter requires a Small plan or higher.", "code": "tier_required"},
+            {
+                "detail": {
+                    "error": "The 'psc' filter requires a Small plan or higher.",
+                    "code": "tier_required",
+                }
+            },
+        ],
+    )
+    @patch("tango.client.httpx.Client.request")
+    def test_403_tier_gate_reason_flat_or_nested(self, mock_request, body):
+        mock_request.return_value = self._error_response(403, body)
+
+        with pytest.raises(
+            TangoAPIError, match=r"status 403: The 'psc' filter requires a Small plan"
+        ):
+            TangoClient(api_key="test-key").list_agencies()
+
+    @patch("tango.client.httpx.Client.request")
+    def test_non_json_error_body_keeps_the_bare_message(self, mock_request):
+        response = self._error_response(502, content=b"<html>Bad Gateway</html>")
+        response.json.side_effect = ValueError("not JSON")
+        mock_request.return_value = response
+
+        with pytest.raises(TangoAPIError) as exc_info:
+            TangoClient(api_key="test-key").list_agencies()
+
+        assert str(exc_info.value) == "API request failed with status 502"
+        assert exc_info.value.response_data == {}
+
     @patch("tango.client.httpx.Client.request")
     def test_network_error(self, mock_request):
         """Test network errors raise TangoAPIError"""