Add BubbleAPIError with centralized error handling for cleaner API and better error details

Author: purificant

src/bubble_data_api_client/__init__.py

@@ -19,6 +19,7 @@
     set_config_provider,
 )
 from bubble_data_api_client.constraints import Constraint, ConstraintType, constraint
+from bubble_data_api_client.exceptions import BubbleAPIError
 from bubble_data_api_client.pool import client_scope, close_clients
 from bubble_data_api_client.types import (
     BubbleField,
@@ -38,6 +39,8 @@
     # client classes
     "BubbleModel",
     "RawClient",
+    # exceptions
+    "BubbleAPIError",
     # query building
     "Constraint",
     "ConstraintType",

src/bubble_data_api_client/client/orm.py

@@ -19,13 +19,12 @@ class User(BubbleModel, typename="user"):
 from collections.abc import AsyncIterator
 from datetime import datetime
 
-import httpx
 from pydantic import BaseModel as PydanticBaseModel
 from pydantic import Field
 
 from bubble_data_api_client.client.raw_client import AdditionalSortField, RawClient
 from bubble_data_api_client.constraints import Constraint, ConstraintType, constraint
-from bubble_data_api_client.exceptions import UnknownFieldError
+from bubble_data_api_client.exceptions import BubbleAPIError, UnknownFieldError
 from bubble_data_api_client.types import BubbleField, OnMultiple
 
 
@@ -91,7 +90,6 @@ async def create(cls, **data: typing.Any) -> typing.Self:
         aliased_data = cls._resolve_aliases(data)
         async with _get_client() as client:
             response = await client.create(cls._typename, aliased_data)
-            response.raise_for_status()
             uid = response.json()["id"]
             return cls(**aliased_data, **{BubbleField.ID: uid})
 
@@ -101,10 +99,9 @@ async def get(cls, uid: str) -> typing.Self | None:
         async with _get_client() as client:
             try:
                 response = await client.retrieve(cls._typename, uid)
-                response.raise_for_status()
                 return cls(**response.json()["response"])
-            except httpx.HTTPStatusError as e:
-                if e.response.status_code == http.HTTPStatus.NOT_FOUND:
+            except BubbleAPIError as e:
+                if e.status_code == http.HTTPStatus.NOT_FOUND:
                     return None
                 raise
 
@@ -130,22 +127,19 @@ async def save(self) -> None:
                 exclude={"uid", "created_date", "modified_date", "slug"},
                 by_alias=True,
             )
-            response = await client.update(self._typename, self.uid, data)
-            response.raise_for_status()
+            await client.update(self._typename, self.uid, data)
 
     @classmethod
     async def update(cls, uid: str, **data: typing.Any) -> None:
         """Update specific fields on a thing by its unique ID."""
         aliased_data = cls._resolve_aliases(data)
         async with _get_client() as client:
-            response = await client.update(cls._typename, uid, aliased_data)
-            response.raise_for_status()
+            await client.update(cls._typename, uid, aliased_data)
 
     async def delete(self) -> None:
         """Delete this thing from Bubble."""
         async with _get_client() as client:
-            response = await client.delete(self._typename, self.uid)
-            response.raise_for_status()
+            await client.delete(self._typename, self.uid)
 
     @classmethod
     async def find(
@@ -184,7 +178,6 @@ async def find(
                 exclude_remaining=exclude_remaining,
                 additional_sort_fields=additional_sort_fields,
             )
-            response.raise_for_status()
             return [cls(**item) for item in response.json()["response"]["results"]]
 
     @classmethod
@@ -210,7 +203,6 @@ async def find_iter(
                     descending=descending,
                     additional_sort_fields=additional_sort_fields,
                 )
-                response.raise_for_status()
                 body = response.json()["response"]
                 for item in body["results"]:
                     yield cls(**item)

src/bubble_data_api_client/client/raw_client.py

@@ -13,7 +13,12 @@
 import httpx
 
 from bubble_data_api_client.constraints import Constraint, ConstraintType, constraint
-from bubble_data_api_client.exceptions import InvalidOnMultipleError, MultipleMatchesError, PartialFailureError
+from bubble_data_api_client.exceptions import (
+    BubbleAPIError,
+    InvalidOnMultipleError,
+    MultipleMatchesError,
+    PartialFailureError,
+)
 from bubble_data_api_client.transport import Transport
 from bubble_data_api_client.types import BubbleField, CreateOrUpdateResult, OnMultiple
 
@@ -142,8 +147,8 @@ async def exists(
             # ID lookup: retrieve + 404 is optimal (no JSON parsing needed)
             try:
                 await self.retrieve(typename, uid)
-            except httpx.HTTPStatusError as e:
-                if e.response.status_code == http.HTTPStatus.NOT_FOUND:
+            except BubbleAPIError as e:
+                if e.status_code == http.HTTPStatus.NOT_FOUND:
                     return False
                 raise
             else:
@@ -223,16 +228,14 @@ async def create_or_update(
         if not results:
             merged_create_data = {**match, **(create_data or {})}
             response = await self.create(typename=typename, data=merged_create_data)
-            response.raise_for_status()
             uid: str = response.json()["id"]
             return {"uids": [uid], "created": True}
 
         # single match: update it (or skip if no update_data)
         if len(results) == 1:
             uid = results[0][BubbleField.ID]
             if update_data:
-                response = await self.update(typename=typename, uid=uid, data=update_data)
-                response.raise_for_status()
+                await self.update(typename=typename, uid=uid, data=update_data)
             return {"uids": [uid], "created": False}
 
         # multiple matches: handle according to strategy
@@ -243,8 +246,7 @@ async def create_or_update(
             case OnMultiple.UPDATE_FIRST:
                 uid = results[0][BubbleField.ID]
                 if update_data:
-                    response = await self.update(typename=typename, uid=uid, data=update_data)
-                    response.raise_for_status()
+                    await self.update(typename=typename, uid=uid, data=update_data)
                 return {"uids": [uid], "created": False}
 
             case OnMultiple.UPDATE_ALL:
@@ -263,7 +265,6 @@ async def create_or_update(
                         if isinstance(item, BaseException):
                             failed.append((uid, item))
                         else:
-                            item.raise_for_status()
                             succeeded.append(uid)
 
                     if failed:
@@ -286,8 +287,7 @@ async def create_or_update(
 
                 # update first so data is preserved even if deletes fail
                 if update_data:
-                    response = await self.update(typename=typename, uid=keep_uid, data=update_data)
-                    response.raise_for_status()
+                    await self.update(typename=typename, uid=keep_uid, data=update_data)
 
                 # delete duplicates concurrently, letting all complete before checking errors
                 delete_results = await asyncio.gather(
@@ -301,7 +301,6 @@ async def create_or_update(
                     if isinstance(item, BaseException):
                         failed.append((uid, item))
                     else:
-                        item.raise_for_status()
                         succeeded.append(uid)
 
                 if failed:

src/bubble_data_api_client/exceptions.py

@@ -1,5 +1,9 @@
 """Exception types for Bubble Data API errors."""
 
+import typing
+
+import httpx
+
 
 class BubbleError(Exception):
     """Base class for all exceptions raised by the library."""
@@ -17,6 +21,52 @@ class BubbleHttpError(BubbleError):
     """Base class for all high level HTTP errors."""
 
 
+class BubbleAPIError(BubbleHttpError):
+    """Structured error from Bubble API responses.
+
+    Attributes:
+        status_code: HTTP status code (400, 404, 500, etc.)
+        status: Bubble error status string ("MISSING_DATA", etc.) or None if unparseable
+        message: Human-readable error message from Bubble or raw response text
+        response: Original httpx.Response for advanced inspection
+    """
+
+    def __init__(
+        self,
+        status_code: int,
+        status: str | None,
+        message: str,
+        response: httpx.Response,
+    ) -> None:
+        """Create error with parsed Bubble API response data."""
+        self.status_code = status_code
+        self.status = status
+        self.message = message
+        self.response = response
+        super().__init__(message)
+
+    @classmethod
+    def from_response(cls, response: httpx.Response) -> typing.Self:
+        """Parse Bubble error response and construct exception."""
+        status: str | None = None
+        message: str = response.text
+
+        try:
+            data = response.json()
+            body = data.get("body", {})
+            status = body.get("status")
+            message = body.get("message", response.text)
+        except Exception:  # noqa: S110
+            pass  # fall back to raw response text
+
+        return cls(
+            status_code=response.status_code,
+            status=status,
+            message=message,
+            response=response,
+        )
+
+
 class BubbleUnauthorizedError(BubbleHttpError):
     """Raised when the user is not authorized to access a resource."""
 

src/bubble_data_api_client/transport.py

@@ -6,6 +6,7 @@
 import httpx
 
 from bubble_data_api_client.config import get_config
+from bubble_data_api_client.exceptions import BubbleAPIError
 from bubble_data_api_client.pool import get_client
 
 
@@ -15,7 +16,11 @@ class Transport:
     Responsibilities:
     - Obtains a pooled httpx client on entry
     - Provides HTTP verb methods (get, post, patch, put, delete)
-    - Raises on non-2xx responses
+    - Raises BubbleAPIError on non-2xx responses (single point of HTTP error handling)
+
+    All HTTP operations in this library flow through Transport.request(), which is
+    the only place that checks response status and raises errors. Higher layers
+    (RawClient, ORM) can assume that if a response is returned, it was successful.
 
     HTTP client configuration (headers, retries, timeouts) is handled by
     the http_client module. Connection pooling is handled by the pool module.
@@ -49,7 +54,14 @@ async def request(
         params: dict[str, str] | None = None,
         headers: dict[str, str] | None = None,
     ) -> httpx.Response:
-        """Execute an HTTP request with optional retry logic."""
+        """Execute an HTTP request with optional retry logic.
+
+        This is the single point of HTTP error handling for the library.
+        Non-2xx responses are converted to BubbleAPIError before returning.
+
+        Raises:
+            BubbleAPIError: On any non-2xx HTTP response.
+        """
 
         async def do_request() -> httpx.Response:
             response: httpx.Response = await self._http.request(
@@ -60,7 +72,10 @@ async def do_request() -> httpx.Response:
                 params=params,
                 headers=headers,
             )
-            response.raise_for_status()
+            try:
+                response.raise_for_status()
+            except httpx.HTTPStatusError as e:
+                raise BubbleAPIError.from_response(response) from e
             return response
 
         retry = get_config().get("retry")

src/tests/unit/client/test_raw_client.py

@@ -2,6 +2,7 @@
 import pytest
 import respx
 
+from bubble_data_api_client import BubbleAPIError
 from bubble_data_api_client.client import raw_client
 
 
@@ -147,10 +148,10 @@ async def test_exists_by_uid_error_reraises(configured_client: None) -> None:
     )
 
     async with raw_client.RawClient() as client:
-        with pytest.raises(httpx.HTTPStatusError) as exc_info:
+        with pytest.raises(BubbleAPIError) as exc_info:
             await client.exists(typename="customer", uid="123x456")
 
-    assert exc_info.value.response.status_code == 500
+    assert exc_info.value.status_code == 500
 
 
 @respx.mock

src/tests/unit/test_transport.py

@@ -5,7 +5,7 @@
 import respx
 import tenacity
 
-from bubble_data_api_client import configure, http_client
+from bubble_data_api_client import BubbleAPIError, configure, http_client
 from bubble_data_api_client.pool import close_clients
 from bubble_data_api_client.transport import Transport
 
@@ -42,9 +42,9 @@ async def test_transport_no_retry_fails_immediately(clean_client_pool: None) ->
     route = respx.get("https://test.example.com/test").mock(return_value=httpx.Response(500))
 
     async with Transport() as transport:
-        with pytest.raises(httpx.HTTPStatusError) as exc_info:
+        with pytest.raises(BubbleAPIError) as exc_info:
             await transport.get("/test")
-        assert exc_info.value.response.status_code == 500
+        assert exc_info.value.status_code == 500
 
     assert route.call_count == 1
 
@@ -58,7 +58,7 @@ async def test_transport_retry_succeeds_after_failures(clean_client_pool: None)
         retry=tenacity.AsyncRetrying(
             stop=tenacity.stop_after_attempt(3),
             wait=tenacity.wait_none(),
-            retry=tenacity.retry_if_exception_type(httpx.HTTPStatusError),
+            retry=tenacity.retry_if_exception_type(BubbleAPIError),
         ),
     )
 
@@ -86,7 +86,7 @@ async def test_transport_retry_exhausted(clean_client_pool: None) -> None:
         retry=tenacity.AsyncRetrying(
             stop=tenacity.stop_after_attempt(3),
             wait=tenacity.wait_none(),
-            retry=tenacity.retry_if_exception_type(httpx.HTTPStatusError),
+            retry=tenacity.retry_if_exception_type(BubbleAPIError),
         ),
     )