fix: keep the API's suggestion in session creation errors

tests/test_driver.py

@@ -316,6 +316,31 @@ def test_http_timeout_on_post(self, mock_post):
         _, kwargs = mock_post.call_args
         assert kwargs["timeout"] == DEFAULT_HTTP_TIMEOUT
 
+    @patch("wherobots.db.driver.requests.post")
+    def test_session_error_keeps_suggestion(self, mock_post):
+        """A refused session's error relays the API's suggestion."""
+        post_resp = MagicMock()
+        post_resp.status_code = 403
+        post_resp.raise_for_status.side_effect = requests.HTTPError(response=post_resp)
+        post_resp.json.return_value = {
+            "errors": [
+                {
+                    "message": "Insufficient Quota",
+                    "details": "The total requested cpu exceed the quota",
+                    "suggestion": "Contact us to request a quota increase.",
+                }
+            ]
+        }
+        mock_post.return_value = post_resp
+
+        with pytest.raises(InterfaceError) as exc_info:
+            connect(api_key="test-key")
+
+        assert str(exc_info.value) == (
+            "Failed to create SQL session: Insufficient Quota: The total "
+            "requested cpu exceed the quota. Contact us to request a quota increase."
+        )
+
     @patch("wherobots.db.driver.requests.get")
     @patch("wherobots.db.driver.requests.post")
     def test_http_timeout_on_get(self, mock_post, mock_get):

wherobots/db/driver.py

@@ -239,7 +239,11 @@ def connect(
             info = e.response.json()
             errors = info.get("errors", [])
             if errors and isinstance(errors, list):
-                details = f"{errors[0]['message']}: {errors[0]['details']}"
+                error = errors[0]
+                details = f"{error['message']}: {error['details']}"
+                # The way out of the error, e.g. how to raise a quota.
+                if suggestion := error.get("suggestion"):
+                    details = f"{details.rstrip('.')}. {suggestion}"
         except requests.JSONDecodeError:
             pass
         raise InterfaceError(f"Failed to create SQL session: {details}") from e