Polish

Author: vdusek

docs/04_upgrading/upgrading_to_v3.mdx

@@ -186,6 +186,44 @@ The default timeout tier assigned to each method on non-storage resource clients
 
 If your code relied on the previous global timeout behavior, review the timeout tier on the methods you use and adjust via the `timeout` parameter or by overriding tier defaults on the <ApiLink to="class/ApifyClient">`ApifyClient`</ApiLink> constructor (see [Tiered timeout system](#tiered-timeout-system) above).
 
+## Exception subclasses for API errors
+
+<ApiLink to="class/ApifyApiError">`ApifyApiError`</ApiLink> now dispatches to a dedicated subclass based on the HTTP status code of the failed response. Instantiating `ApifyApiError` directly still works — it returns the most specific subclass for the status — so existing `except ApifyApiError` handlers are unaffected.
+
+The following subclasses are available:
+
+| Status | Subclass |
+|---|---|
+| 400 | <ApiLink to="class/InvalidRequestError">`InvalidRequestError`</ApiLink> |
+| 401 | <ApiLink to="class/UnauthorizedError">`UnauthorizedError`</ApiLink> |
+| 403 | <ApiLink to="class/ForbiddenError">`ForbiddenError`</ApiLink> |
+| 404 | <ApiLink to="class/NotFoundError">`NotFoundError`</ApiLink> |
+| 409 | <ApiLink to="class/ConflictError">`ConflictError`</ApiLink> |
+| 429 | <ApiLink to="class/RateLimitError">`RateLimitError`</ApiLink> |
+| 5xx | <ApiLink to="class/ServerError">`ServerError`</ApiLink> |
+
+You can now branch on error kind without inspecting `status_code` or `type`:
+
+```python
+from apify_client import ApifyClient
+from apify_client.errors import NotFoundError, RateLimitError
+
+client = ApifyClient(token='MY-APIFY-TOKEN')
+
+try:
+    run = client.run('some-run-id').get()
+except NotFoundError:
+    run = None
+except RateLimitError:
+    ...
+```
+
+### Behavior change: `.get()` now returns `None` on any 404
+
+As a consequence of the dispatch above, `.get()`-style convenience methods — which use `catch_not_found_or_throw` internally to swallow 404 responses and return `None` — now swallow **every** 404, regardless of the `error.type` string in the response body. Previously only 404 responses carrying the types `record-not-found` or `record-or-token-not-found` were swallowed; any other 404 was re-raised as `ApifyApiError`.
+
+In practice this matters only if you relied on a `.get()` call raising for a 404 with an unusual error type — such cases now return `None` instead. If your code needs to distinguish between "resource missing" and "404 with an unexpected type", inspect `.type` on the returned response or catch <ApiLink to="class/NotFoundError">`NotFoundError`</ApiLink> from non-`.get()` calls that do not use `catch_not_found_or_throw`.
+
 ## Snake_case `sort_by` values on `actors().list()`
 
 The `sort_by` parameter of <ApiLink to="class/ActorCollectionClient#list">`ActorCollectionClient.list()`</ApiLink> and <ApiLink to="class/ActorCollectionClientAsync#list">`ActorCollectionClientAsync.list()`</ApiLink> now accepts pythonic snake_case values instead of the raw camelCase values used by the API.

src/apify_client/errors.py

@@ -13,30 +13,19 @@
 
 @docs_group('Errors')
 class ApifyClientError(Exception):
-    """Base class for all Apify API client errors.
-
-    All custom exceptions defined by this package inherit from this class, making it convenient
-    to catch any client-related error with a single except clause.
-    """
+    """Base class for all Apify API client errors."""
 
 
 @docs_group('Errors')
 class ApifyApiError(ApifyClientError):
     """Error raised when the Apify API returns an error response.
 
-    This error is raised when an HTTP request to the Apify API succeeds at the transport level
-    but the server returns an error status code. Rate limit (HTTP 429) and server errors (HTTP 5xx)
-    are retried automatically before this error is raised, while client errors (HTTP 4xx) are raised
-    immediately.
+    Instantiating `ApifyApiError` dispatches to the subclass matching the HTTP status code (e.g. 404 → `NotFoundError`,
+    any 5xx → `ServerError`). Unmapped statuses stay on `ApifyApiError`. Existing `except ApifyApiError` handlers keep
+    working because every subclass inherits from this class.
 
-    Instantiating `ApifyApiError` directly dispatches to a more specific subclass based on the
-    HTTP status code of the response (e.g. a 404 response produces a `NotFoundError`). Existing
-    `except ApifyApiError` handlers continue to match because every subclass inherits from this
-    class. Statuses without a dedicated subclass fall back to `ApifyApiError` itself.
-
-    The `type`, `message` and `data` fields from the API response body are exposed as attributes
-    for inspection, but they are treated as non-authoritative metadata — dispatch is driven by the
-    status code only, which is more stable than the per-endpoint `error.type` strings.
+    The `type`, `message` and `data` fields from the response body are exposed for inspection but are treated as
+    non-authoritative metadata — dispatch is driven by the status code only.
 
     Attributes:
         message: The error message from the API response.
@@ -47,6 +36,9 @@ class ApifyApiError(ApifyClientError):
         data: Additional error data from the API response.
     """
 
+    # Subclasses in `_STATUS_TO_CLASS` must keep the `(response, attempt, method='GET')` constructor signature —
+    # `__new__` forwards those arguments verbatim.
+
     def __new__(cls, response: HttpResponse, attempt: int, method: str = 'GET') -> Self:  # noqa: ARG004
         """Dispatch to the subclass matching the response's HTTP status code, if any."""
         target_cls: type[ApifyApiError] = cls
@@ -67,36 +59,35 @@ def __init__(self, response: HttpResponse, attempt: int, method: str = 'GET') ->
             attempt: The attempt number when the request failed (1-indexed).
             method: The HTTP method of the failed request.
         """
-        payload = _extract_error_payload(response)
+        payload = self._extract_error_payload(response)
 
         self.message: str | None = f'Unexpected error: {response.text}'
         self.type: str | None = None
         self.data = dict[str, str]()
 
         if payload is not None:
-            self.message = payload['message']
-            self.type = payload['type']
+            self.message = payload.get('message', self.message)
+            self.type = payload.get('type')
             if 'data' in payload:
                 self.data = payload['data']
 
         super().__init__(self.message)
 
-        self.name = 'ApifyApiError'
         self.status_code = response.status_code
         self.attempt = attempt
         self.http_method = method
 
-
-def _extract_error_payload(response: HttpResponse) -> dict[str, Any] | None:
-    """Return the `error` dict from the response body, or None if absent or unparsable."""
-    try:
-        data = response.json()
-    except ValueError:
-        return None
-    if not isinstance(data, dict):
-        return None
-    error = data.get('error')
-    return error if isinstance(error, dict) else None
+    @staticmethod
+    def _extract_error_payload(response: HttpResponse) -> dict[str, Any] | None:
+        """Return the `error` dict from the response body, or None if absent or unparsable."""
+        try:
+            data = response.json()
+        except ValueError:
+            return None
+        if not isinstance(data, dict):
+            return None
+        error = data.get('error')
+        return error if isinstance(error, dict) else None
 
 
 @docs_group('Errors')
@@ -128,37 +119,26 @@ class ConflictError(ApifyApiError):
 class RateLimitError(ApifyApiError):
     """Raised when the Apify API returns an HTTP 429 Too Many Requests response.
 
-    Rate-limited requests are retried automatically; this error is only raised after all
-    retry attempts have been exhausted.
+    Rate-limited requests are retried automatically; this error is only raised after all retry attempts have been
+    exhausted.
     """
 
 
 @docs_group('Errors')
 class ServerError(ApifyApiError):
     """Raised when the Apify API returns an HTTP 5xx response.
 
-    Server errors are retried automatically; this error is only raised after all
-    retry attempts have been exhausted.
+    Server errors are retried automatically; this error is only raised after all retry attempts have been exhausted.
     """
 
 
-_STATUS_TO_CLASS: dict[int, type[ApifyApiError]] = {
-    400: InvalidRequestError,
-    401: UnauthorizedError,
-    403: ForbiddenError,
-    404: NotFoundError,
-    409: ConflictError,
-    429: RateLimitError,
-}
-
-
 @docs_group('Errors')
 class InvalidResponseBodyError(ApifyClientError):
     """Error raised when a response body cannot be parsed.
 
-    This typically occurs when the API returns a partial or malformed JSON response, for example
-    due to a network interruption. The client retries such requests automatically, so this error
-    is only raised after all retry attempts have been exhausted.
+    This typically occurs when the API returns a partial or malformed JSON response, for example due to a network
+    interruption. The client retries such requests automatically, so this error is only raised after all retry
+    attempts have been exhausted.
     """
 
     def __init__(self, response: HttpResponse) -> None:
@@ -169,6 +149,15 @@ def __init__(self, response: HttpResponse) -> None:
         """
         super().__init__('Response body could not be parsed')
 
-        self.name = 'InvalidResponseBodyError'
         self.code = 'invalid-response-body'
         self.response = response
+
+
+_STATUS_TO_CLASS: dict[int, type[ApifyApiError]] = {
+    400: InvalidRequestError,
+    401: UnauthorizedError,
+    403: ForbiddenError,
+    404: NotFoundError,
+    409: ConflictError,
+    429: RateLimitError,
+}

tests/unit/test_client_errors.py

@@ -7,7 +7,16 @@
 from werkzeug import Response
 
 from apify_client._http_clients import ImpitHttpClient, ImpitHttpClientAsync
-from apify_client.errors import ApifyApiError, ForbiddenError, NotFoundError, ServerError
+from apify_client.errors import (
+    ApifyApiError,
+    ConflictError,
+    ForbiddenError,
+    InvalidRequestError,
+    NotFoundError,
+    RateLimitError,
+    ServerError,
+    UnauthorizedError,
+)
 
 if TYPE_CHECKING:
     from pytest_httpserver import HTTPServer
@@ -163,6 +172,35 @@ def test_apify_api_error_falls_back_for_unmapped_status(httpserver: HTTPServer)
     assert exc.value.type == 'whatever'
 
 
+@pytest.mark.parametrize(
+    ('status_code', 'expected_cls'),
+    [
+        pytest.param(400, InvalidRequestError, id='400 → InvalidRequestError'),
+        pytest.param(401, UnauthorizedError, id='401 → UnauthorizedError'),
+        pytest.param(403, ForbiddenError, id='403 → ForbiddenError'),
+        pytest.param(404, NotFoundError, id='404 → NotFoundError'),
+        pytest.param(409, ConflictError, id='409 → ConflictError'),
+        pytest.param(429, RateLimitError, id='429 → RateLimitError'),
+    ],
+)
+def test_apify_api_error_dispatches_all_mapped_statuses(
+    httpserver: HTTPServer, status_code: int, expected_cls: type[ApifyApiError]
+) -> None:
+    """Every status in `_STATUS_TO_CLASS` dispatches to its matching subclass."""
+    httpserver.expect_request('/dispatch_all').respond_with_json(
+        {'error': {'type': 'some-type', 'message': 'msg'}}, status=status_code
+    )
+    # Use max_retries=1 so retryable statuses (429) don't loop during the test.
+    client = ImpitHttpClient(max_retries=1)
+
+    with pytest.raises(expected_cls) as exc:
+        client.call(method='GET', url=str(httpserver.url_for('/dispatch_all')))
+
+    assert type(exc.value) is expected_cls
+    assert isinstance(exc.value, ApifyApiError)
+    assert exc.value.status_code == status_code
+
+
 def test_apify_api_error_falls_back_for_unparsable_body(httpserver: HTTPServer) -> None:
     """When the body can't be parsed, status-based dispatch still applies and `.type` is None."""
     httpserver.expect_request('/unparsable').respond_with_data('<not json>', status=418, content_type='text/html')