refactor: drop SDK error classes, keep apify.errors as a pure re-export

vdusek · vdusek · commit d12c0e04bbeb · 2026-06-19T16:48:32.000+02:00
diff --git a/docs/02_concepts/13_exceptions.mdx b/docs/02_concepts/13_exceptions.mdx
@@ -9,11 +9,11 @@ import RetryTimedOutSource from '!!raw-loader!roa-loader!./code/13_retry_timed_o
 import ApiLink from '@theme/ApiLink';
 import RunnableCodeBlock from '@site/src/components/RunnableCodeBlock';
 
-When an Actor runs, failures surface from two places. The [Apify API client](https://docs.apify.com/api/client/python) raises typed exceptions for failed API requests. The SDK adds a small set of its own errors for outcomes the client cannot express, such as a sub-Actor run that finishes in a failure state. Both are available from the `apify.errors` module.
+When you run an Actor, exceptions come from a few layers: the Apify API client for failed API requests, the Apify SDK for misuse and invalid input, and the libraries you build on, such as Crawlee. This page maps the ones you are most likely to meet and how to approach each.
 
 ## Errors from the Apify API
 
-Every SDK operation that talks to the Apify API can raise `ApifyApiError`. This includes <ApiLink to="class/Actor#start">`Actor.start`</ApiLink>, <ApiLink to="class/Actor#call">`Actor.call`</ApiLink>, `Actor.abort`, `Actor.metamorph`, `Actor.add_webhook`, charging, and all storage operations on datasets, key-value stores, and request queues. The SDK raises these client exceptions as-is. It does not wrap them, so you keep the HTTP status code, the error type, and the response data on the exception.
+Every SDK operation that talks to the Apify API can raise `ApifyApiError`. This includes <ApiLink to="class/Actor#start">`Actor.start`</ApiLink>, <ApiLink to="class/Actor#call">`Actor.call`</ApiLink>, `Actor.abort`, `Actor.metamorph`, `Actor.add_webhook`, charging, and all storage operations on datasets, key-value stores, and request queues. The SDK raises these client exceptions as-is, so you keep the HTTP status code, the error type, and the response data on the exception.
 
 `ApifyApiError` dispatches to a subclass based on the HTTP status code:
 
@@ -24,34 +24,39 @@ Every SDK operation that talks to the Apify API can raise `ApifyApiError`. This
 - `ServerError` for any 5xx response.
 - `InvalidRequestError` (400) when the API rejects the request as malformed.
 
-The client retries rate-limited and server errors on its own, so you only see `RateLimitError` or `ServerError` once those retries are exhausted. For convenience, `apify.errors` re-exports the whole client error hierarchy, so you can import everything from one place:
+The client retries rate-limited and server errors on its own, so you only see `RateLimitError` or `ServerError` once those retries are exhausted. The `apify.errors` module re-exports the whole client error hierarchy, so you can import everything from one place:
 
 ```python
 from apify.errors import ApifyApiError, NotFoundError, RateLimitError
 ```
 
-## Actor run failures
-
-<ApiLink to="class/Actor#call">`Actor.call`</ApiLink> and <ApiLink to="class/Actor#call_task">`Actor.call_task`</ApiLink> wait for the run to finish and return it, whatever its final status. A finished run can be `SUCCEEDED`, `FAILED`, `ABORTED`, or `TIMED-OUT`, so check `run.status` before you rely on the run's output.
-
-To turn a failed run into an exception, build one from the run with <ApiLink to="class/ActorRunError">`ActorRunError`</ApiLink>`.from_run()`. It returns an <ApiLink to="class/ActorTimeoutError">`ActorTimeoutError`</ApiLink> for a timed-out run, and an `ActorRunError` otherwise. Both carry the run metadata you need to decide what to do next: `run_id`, `status`, `exit_code`, and `status_message`. Every SDK error also derives from <ApiLink to="class/ActorError">`ActorError`</ApiLink> and exposes a stable `code` and a `retryable` flag.
-
-## Handling errors
-
-Wrap the call to catch an API failure, then inspect the finished run and escalate it if needed:
+Catch `ApifyApiError` to handle any API failure in one place, then branch on the subclass or the HTTP `status_code`. To react to a specific failure, catch its subclass first:
 
 <RunnableCodeBlock className="language-python" language="python">
     {HandleCallErrorsSource}
 </RunnableCodeBlock>
 
-## Retrying a timed-out run
+## Misuse and invalid input
+
+The SDK raises standard Python exceptions when it is used incorrectly or given invalid input. These point to a bug or a bad argument in your code, so the fix is to correct the call rather than to catch the exception.
 
-A timed-out run is the one failure where retrying can help, as long as you give it more time. `ActorTimeoutError` sets `retryable` to `True` to mark this. Retry with a longer timeout rather than the same one:
+- `RuntimeError` when an `Actor` method is used outside the `async with Actor:` block, either before initialization or after exit, or when the Actor is initialized twice.
+- `ValueError` for an invalid argument, such as a malformed `timeout`, an invalid proxy configuration, charging an automatically charged event by hand, or pushing data that is not JSON-serializable or is over the size limit.
+- `TypeError` for an argument of the wrong type.
+- `ConnectionError` when <ApiLink to="class/Actor#create_proxy_configuration">`Actor.create_proxy_configuration`</ApiLink> verifies Apify Proxy access and the proxy reports that you have none.
+
+## Run failures
+
+<ApiLink to="class/Actor#call">`Actor.call`</ApiLink> and <ApiLink to="class/Actor#call_task">`Actor.call_task`</ApiLink> wait for the run to finish and return it, whatever its final status. A finished run can be `SUCCEEDED`, `FAILED`, `ABORTED`, or `TIMED-OUT`, so check `run.status` before you rely on the run's output. A timed-out run is the one case where retrying can help, as long as you give it more time:
 
 <RunnableCodeBlock className="language-python" language="python">
     {RetryTimedOutSource}
 </RunnableCodeBlock>
 
+## Errors while crawling
+
+If your Actor runs a [Crawlee](https://crawlee.dev/python) crawler, failures inside request handlers surface as Crawlee exceptions, and Crawlee manages retries and session rotation around them. For details, see the [Crawlee documentation](https://crawlee.dev/python).
+
 ## The pay-per-event charge limit
 
 Reaching the pay-per-event charge limit does not raise an error. The SDK caps charging and data pushing instead, and your Actor keeps running. To detect the limit, check the `event_charge_limit_reached` field on the `ChargeResult` returned by <ApiLink to="class/Actor#charge">`Actor.charge`</ApiLink> or `Actor.push_data`. For details, see [Pay-per-event monetization](./pay-per-event).
diff --git a/docs/02_concepts/code/13_handle_call_errors.py b/docs/02_concepts/code/13_handle_call_errors.py
@@ -1,22 +1,26 @@
 import asyncio
 
 from apify import Actor
-from apify.errors import ActorRunError, ApifyApiError
+from apify.errors import ApifyApiError, NotFoundError
 
 
 async def main() -> None:
     async with Actor:
         try:
             run = await Actor.call('apify/web-scraper', run_input={'startUrls': []})
+        except NotFoundError:
+            # Catch a specific subclass first.
+            Actor.log.error('The Actor to call does not exist.')
+            return
         except ApifyApiError as exc:
-            # The Apify API rejected the request, e.g. the Actor does not exist or
-            # the token is invalid. The HTTP status code is on the exception.
-            Actor.log.error(f'Could not start the Actor: {exc} (HTTP {exc.status_code}).')
+            # Any other API failure, e.g. an invalid token or a server error.
+            Actor.log.error(f'Calling the Actor failed: {exc} (HTTP {exc.status_code}).')
             return
 
         # `Actor.call` returns the finished run whatever its status, so check it.
         if run.status != 'SUCCEEDED':
-            raise ActorRunError.from_run(run)
+            Actor.log.error(f'Run {run.id} ended with status {run.status}.')
+            return
 
         Actor.log.info(f'Run {run.id} finished successfully.')
 
diff --git a/docs/02_concepts/code/13_retry_timed_out.py b/docs/02_concepts/code/13_retry_timed_out.py
@@ -2,7 +2,6 @@
 from datetime import timedelta
 
 from apify import Actor
-from apify.errors import ActorRunError, ActorTimeoutError
 
 
 async def main() -> None:
@@ -13,18 +12,12 @@ async def main() -> None:
         for attempt in range(1, max_attempts + 1):
             run = await Actor.call('apify/web-scraper', timeout=timeout)
 
-            if run.status == 'SUCCEEDED':
-                Actor.log.info(f'Run {run.id} finished.')
+            if run.status != 'TIMED-OUT' or attempt == max_attempts:
+                Actor.log.info(f'Run {run.id} ended with status {run.status}.')
                 break
 
-            # Build a typed error from the finished run so we can branch on it.
-            error = ActorRunError.from_run(run)
-            if isinstance(error, ActorTimeoutError) and attempt < max_attempts:
-                timeout *= 2
-                Actor.log.warning(f'Timed out, retrying with timeout {timeout}.')
-                continue
-
-            raise error
+            timeout *= 2
+            Actor.log.warning(f'Timed out, retrying with timeout {timeout}.')
 
 
 if __name__ == '__main__':
diff --git a/src/apify/_utils.py b/src/apify/_utils.py
@@ -74,7 +74,6 @@ def is_running_in_ipython() -> bool:
     'Actor',
     'Charging',
     'Configuration',
-    'Errors',
     'Event data',
     'Event managers',
     'Events',
diff --git a/src/apify/errors.py b/src/apify/errors.py
@@ -1,10 +1,8 @@
 from __future__ import annotations
 
-from typing import TYPE_CHECKING
-
-# Re-export the Apify API client's error hierarchy so callers have a single import location for every error the SDK
-# can surface. Any operation that talks to the Apify API raises these as-is; the SDK does not wrap them in its own
-# types. See https://docs.apify.com/api/client/python for the full client error reference.
+# `apify.errors` re-exports the Apify API client's error hierarchy so callers have a single import location for every
+# error raised by an operation that talks to the Apify API. The SDK raises these client exceptions as-is and does not
+# wrap them in its own types. See https://docs.apify.com/api/client/python for the full client error reference.
 from apify_client.errors import (
     ApifyApiError,
     ApifyClientError,
@@ -18,94 +16,7 @@
     UnauthorizedError,
 )
 
-from apify._utils import docs_group
-
-if TYPE_CHECKING:
-    from apify_client._models import Run
-
-
-@docs_group('Errors')
-class ActorError(Exception):
-    """Base class for the Apify SDK's own domain-level errors.
-
-    These describe outcomes that the Apify API client cannot express on its own, such as a finished Actor run that
-    ended in a failure state. Errors that originate from the Apify API surface as `apify_client` exceptions (e.g.
-    `ApifyApiError` and its subclasses), which the SDK re-exports from this module but does not wrap.
-
-    Carries a machine-readable `code` and a `retryable` flag so callers can branch on a failure without parsing the
-    human-readable error message.
-    """
-
-    code: str = 'actor-error'
-    """Stable, machine-readable identifier of the error category."""
-
-    retryable: bool = False
-    """Whether retrying the same operation might succeed (e.g. an Actor run that timed out)."""
-
-    def __init__(
-        self,
-        message: str | None = None,
-        *,
-        code: str | None = None,
-        retryable: bool | None = None,
-    ) -> None:
-        super().__init__(message)
-        if code is not None:
-            self.code = code
-        if retryable is not None:
-            self.retryable = retryable
-
-
-@docs_group('Errors')
-class ActorRunError(ActorError):
-    """Represents an Actor run that reached a terminal failure state (e.g. `FAILED` or `ABORTED`).
-
-    Exposes the run metadata needed to decide what to do next. The SDK does not raise this automatically. `Actor.call`
-    and `Actor.call_task` return the finished run regardless of its status, mirroring the Apify API client. Build this
-    error from a finished run with `from_run` when you want a failed run to surface as an exception in your own code.
-    """
-
-    code = 'actor-run-failed'
-
-    def __init__(self, run: Run) -> None:
-        self.run_id = run.id
-        self.status = run.status
-        self.exit_code = run.exit_code
-        self.status_message = run.status_message
-
-        message = f'Actor run {run.id!r} ended with status {run.status!r}'
-        if run.status_message:
-            message = f'{message}: {run.status_message}'
-
-        super().__init__(message)
-
-    @classmethod
-    def from_run(cls, run: Run) -> ActorRunError:
-        """Build the most specific run error for a terminal Actor run.
-
-        Args:
-            run: The terminal Actor run.
-
-        Returns:
-            An `ActorTimeoutError` for a timed-out run, otherwise an `ActorRunError`.
-        """
-        if run.status == 'TIMED-OUT':
-            return ActorTimeoutError(run)
-        return ActorRunError(run)
-
-
-@docs_group('Errors')
-class ActorTimeoutError(ActorRunError):
-    """Represents an Actor run that exceeded its timeout (`TIMED-OUT`). Retrying with a longer timeout may help."""
-
-    code = 'actor-timed-out'
-    retryable = True
-
-
 __all__ = [
-    'ActorError',
-    'ActorRunError',
-    'ActorTimeoutError',
     'ApifyApiError',
     'ApifyClientError',
     'ConflictError',
diff --git a/tests/unit/test_errors.py b/tests/unit/test_errors.py
@@ -1,98 +1,24 @@
 from __future__ import annotations
 
-from datetime import UTC, datetime
-
 import apify_client.errors as client_errors
-from apify_client._models import Run
-
-from apify.errors import ActorError, ActorRunError, ActorTimeoutError
-
-
-def _make_run(*, status: str, exit_code: int | None = None, status_message: str | None = None) -> Run:
-    return Run.model_validate(
-        {
-            'id': 'run123',
-            'actId': 'act123',
-            'userId': 'user123',
-            'startedAt': datetime.now(UTC).isoformat(),
-            'status': status,
-            'statusMessage': status_message,
-            'exitCode': exit_code,
-            'meta': {'origin': 'DEVELOPMENT'},
-            'buildId': 'build123',
-            'defaultDatasetId': 'ds123',
-            'defaultKeyValueStoreId': 'kvs123',
-            'defaultRequestQueueId': 'rq123',
-            'containerUrl': 'https://container',
-            'buildNumber': '0.0.1',
-            'generalAccess': 'RESTRICTED',
-            'stats': {'restartCount': 0, 'resurrectCount': 0, 'computeUnits': 1},
-            'options': {'build': 'latest', 'timeoutSecs': 4, 'memoryMbytes': 1024, 'diskMbytes': 1024},
-        }
-    )
-
-
-def test_actor_error_defaults() -> None:
-    error = ActorError('something went wrong')
-    assert error.code == 'actor-error'
-    assert error.retryable is False
-    assert str(error) == 'something went wrong'
-
-
-def test_actor_error_overrides_are_instance_scoped() -> None:
-    error = ActorError('boom', code='custom', retryable=True)
-    assert error.code == 'custom'
-    assert error.retryable is True
-    # Overriding on an instance must not leak to the class default.
-    assert ActorError.code == 'actor-error'
-    assert ActorError.retryable is False
-
 
-def test_actor_run_error_is_actor_error() -> None:
-    assert issubclass(ActorRunError, ActorError)
-    assert ActorRunError.code == 'actor-run-failed'
-    assert ActorRunError.retryable is False
-
-
-def test_actor_timeout_error_is_actor_run_error() -> None:
-    assert issubclass(ActorTimeoutError, ActorRunError)
-    assert ActorTimeoutError.code == 'actor-timed-out'
-    assert ActorTimeoutError.retryable is True
-
-
-def test_actor_run_error_carries_run_metadata() -> None:
-    run = _make_run(status='FAILED', exit_code=1, status_message='Actor crashed')
-    error = ActorRunError(run)
-    assert error.run_id == 'run123'
-    assert error.status == 'FAILED'
-    assert error.exit_code == 1
-    assert error.status_message == 'Actor crashed'
-    assert error.retryable is False
-    assert 'run123' in str(error)
-    assert 'Actor crashed' in str(error)
-
-
-def test_actor_run_error_from_run_failed() -> None:
-    error = ActorRunError.from_run(_make_run(status='FAILED'))
-    assert type(error) is ActorRunError
-    assert not error.retryable
-
-
-def test_actor_run_error_from_run_timed_out() -> None:
-    error = ActorRunError.from_run(_make_run(status='TIMED-OUT'))
-    assert isinstance(error, ActorTimeoutError)
-    assert error.retryable is True
-    assert error.run_id == 'run123'
-    assert error.code == 'actor-timed-out'
+import apify.errors as sdk_errors
 
 
 def test_client_errors_are_re_exported() -> None:
     """`apify.errors` re-exports the API client error hierarchy so callers have a single import location."""
-    from apify.errors import ApifyApiError, ApifyClientError, NotFoundError, RateLimitError
-
-    assert ApifyApiError is client_errors.ApifyApiError
-    assert ApifyClientError is client_errors.ApifyClientError
-    assert NotFoundError is client_errors.NotFoundError
-    assert RateLimitError is client_errors.RateLimitError
-    # The re-exported API errors are independent of the SDK's own `ActorError` tree.
-    assert not issubclass(client_errors.ApifyApiError, ActorError)
+    names = [
+        'ApifyApiError',
+        'ApifyClientError',
+        'ConflictError',
+        'ForbiddenError',
+        'InvalidRequestError',
+        'InvalidResponseBodyError',
+        'NotFoundError',
+        'RateLimitError',
+        'ServerError',
+        'UnauthorizedError',
+    ]
+    assert set(sdk_errors.__all__) == set(names)
+    for name in names:
+        assert getattr(sdk_errors, name) is getattr(client_errors, name)
diff --git a/website/docusaurus.config.js b/website/docusaurus.config.js
@@ -9,7 +9,6 @@ const GROUP_ORDER = [
     'Actor',
     'Charging',
     'Configuration',
-    'Errors',
     'Event data',
     'Event managers',
     'Events',
