feat: Add apify.errors domain-level error taxonomy

vdusek · vdusek · commit 9351189e5fc0 · 2026-06-16T12:53:47.000+02:00
diff --git a/src/apify/_utils.py b/src/apify/_utils.py
@@ -74,6 +74,7 @@ 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
@@ -0,0 +1,158 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from apify_client.errors import ForbiddenError as _ForbiddenError
+from apify_client.errors import InvalidRequestError as _InvalidRequestError
+from apify_client.errors import RateLimitError as _RateLimitError
+from apify_client.errors import ServerError as _ServerError
+from apify_client.errors import UnauthorizedError as _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 all domain-level Apify SDK errors.
+
+    Carries a machine-readable `code` and a `retryable` flag so callers can branch on a failure without reading
+    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. a transient rate limit or server error)."""
+
+    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
+
+    @classmethod
+    def from_client_error(cls, error: Exception) -> ActorError:
+        """Map an `apify_client` exception to the matching domain-level error.
+
+        The mapping is driven by the client's typed, HTTP-status-based exceptions. Unmapped client errors (and any
+        other exception) fall back to a plain `ActorError`. The original exception is not chained automatically;
+        callers should use `raise ActorError.from_client_error(err) from err`.
+
+        Args:
+            error: The exception raised by `apify_client`.
+
+        Returns:
+            The corresponding domain-level error.
+        """
+        if isinstance(error, (_UnauthorizedError, _ForbiddenError)):
+            return ActorAuthenticationError(str(error))
+
+        if isinstance(error, _RateLimitError):
+            return ActorRateLimitError(str(error))
+
+        if isinstance(error, _ServerError):
+            return ActorError(str(error), retryable=True)
+
+        if isinstance(error, _InvalidRequestError):
+            return ActorInputValidationError(str(error))
+
+        return ActorError(str(error))
+
+
+@docs_group('Errors')
+class ActorRunError(ActorError):
+    """Raised when an Actor run reaches a terminal failure state (e.g. `FAILED` or `ABORTED`).
+
+    Unlike the HTTP-derived errors, this one is derived from the run itself, so it exposes the run metadata needed
+    to decide what to do next.
+    """
+
+    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):
+    """Raised when an Actor run exceeds its timeout (`TIMED-OUT`). Retrying with a longer timeout may help."""
+
+    code = 'actor-timed-out'
+    retryable = True
+
+
+@docs_group('Errors')
+class ActorInputValidationError(ActorError, ValueError):
+    """Raised when input fails validation.
+
+    Subclasses `ValueError` so existing `except ValueError` handlers keep catching it.
+    """
+
+    code = 'input-validation-error'
+
+
+@docs_group('Errors')
+class ActorChargeLimitExceededError(ActorError):
+    """Raised when an Actor run hits its configured maximum total charge (`max_total_charge_usd`)."""
+
+    code = 'charge-limit-exceeded'
+
+
+@docs_group('Errors')
+class ActorAuthenticationError(ActorError):
+    """Raised when an API request is unauthorized or forbidden (HTTP 401 / 403)."""
+
+    code = 'authentication-error'
+
+
+@docs_group('Errors')
+class ActorRateLimitError(ActorError):
+    """Raised when the Apify API rate limit is exceeded (HTTP 429). Retryable after a backoff."""
+
+    code = 'rate-limit-exceeded'
+    retryable = True
+
+
+__all__ = [
+    'ActorAuthenticationError',
+    'ActorChargeLimitExceededError',
+    'ActorError',
+    'ActorInputValidationError',
+    'ActorRateLimitError',
+    'ActorRunError',
+    'ActorTimeoutError',
+]
diff --git a/tests/unit/actor/test_configuration.py b/tests/unit/actor/test_configuration.py
@@ -392,21 +392,3 @@ def test_actor_storage_json_env_var(monkeypatch: pytest.MonkeyPatch) -> None:
     assert config.actor_storages['datasets'] == datasets
     assert config.actor_storages['request_queues'] == request_queues
     assert config.actor_storages['key_value_stores'] == key_value_stores
-
-
-@pytest.mark.parametrize(
-    ('env_var', 'attr', 'expected'),
-    [
-        ('APIFY_TIMEOUT_AT', 'timeout_at', None),
-        ('ACTOR_MAX_PAID_DATASET_ITEMS', 'max_paid_dataset_items', None),
-        ('ACTOR_MAX_TOTAL_CHARGE_USD', 'max_total_charge_usd', None),
-        ('APIFY_USER_IS_PAYING', 'user_is_paying', False),
-    ],
-)
-def test_typed_env_var_empty_string_falls_back_to_default(
-    monkeypatch: pytest.MonkeyPatch, env_var: str, attr: str, expected: object
-) -> None:
-    """Platform may set a typed env var to '' instead of leaving it unset; that must not crash `Actor.init()`."""
-    monkeypatch.setenv(env_var, '')
-    config = ApifyConfiguration()
-    assert getattr(config, attr) == expected
diff --git a/tests/unit/test_errors.py b/tests/unit/test_errors.py
@@ -0,0 +1,184 @@
+from __future__ import annotations
+
+from datetime import UTC, datetime
+from typing import Any, cast
+
+import pytest
+
+from apify_client._models import Run
+from apify_client.errors import (
+    ApifyApiError,
+    ConflictError,
+    ForbiddenError,
+    InvalidRequestError,
+    NotFoundError,
+    ServerError,
+    UnauthorizedError,
+)
+from apify_client.errors import RateLimitError as ClientRateLimitError
+
+import apify
+from apify.errors import (
+    ActorAuthenticationError,
+    ActorChargeLimitExceededError,
+    ActorError,
+    ActorInputValidationError,
+    ActorRateLimitError,
+    ActorRunError,
+    ActorTimeoutError,
+)
+
+
+class _FakeResponse:
+    """Minimal stand-in for `apify_client`'s HTTP response, enough to build its API errors."""
+
+    def __init__(self, status_code: int) -> None:
+        self.status_code = status_code
+        self.text = 'error text'
+
+    def json(self) -> dict[str, Any]:
+        return {'error': {'message': 'boom', 'type': 'some-error-type'}}
+
+
+def _client_error(error_cls: type[ApifyApiError], status_code: int) -> ApifyApiError:
+    return error_cls(cast('Any', _FakeResponse(status_code)), 1)
+
+
+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 == 'apify-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 == 'apify-error'
+    assert ActorError.retryable is False
+
+
+@pytest.mark.parametrize(
+    ('error_cls', 'expected_code', 'expected_retryable'),
+    [
+        (ActorRateLimitError, 'rate-limit-exceeded', True),
+        (ActorTimeoutError, 'actor-timed-out', True),
+        (ActorAuthenticationError, 'authentication-error', False),
+        (ActorChargeLimitExceededError, 'charge-limit-exceeded', False),
+        (ActorInputValidationError, 'input-validation-error', False),
+        (ActorRunError, 'actor-run-failed', False),
+    ],
+)
+def test_subclass_codes_and_retryable(
+    error_cls: type[ActorError], expected_code: str, *, expected_retryable: bool
+) -> None:
+    assert error_cls.code == expected_code
+    assert error_cls.retryable is expected_retryable
+    assert issubclass(error_cls, ActorError)
+
+
+def test_input_validation_error_is_value_error() -> None:
+    """`except ValueError` must still catch `ActorInputValidationError`."""
+    with pytest.raises(ValueError, match='bad input'):
+        raise ActorInputValidationError('bad input')
+
+
+def test_actor_timeout_error_is_actor_run_error() -> None:
+    assert issubclass(ActorTimeoutError, ActorRunError)
+
+
+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'
+
+
+@pytest.mark.parametrize(
+    ('client_error', 'expected_cls', 'expected_retryable'),
+    [
+        (_client_error(UnauthorizedError, 401), ActorAuthenticationError, False),
+        (_client_error(ForbiddenError, 403), ActorAuthenticationError, False),
+        (_client_error(ClientRateLimitError, 429), ActorRateLimitError, True),
+        (_client_error(ServerError, 500), ActorError, True),
+        (_client_error(InvalidRequestError, 400), ActorInputValidationError, False),
+        (_client_error(NotFoundError, 404), ActorError, False),
+        (_client_error(ConflictError, 409), ActorError, False),
+    ],
+)
+def test_from_client_error_mapping(
+    client_error: ApifyApiError,
+    expected_cls: type[ActorError],
+    *,
+    expected_retryable: bool,
+) -> None:
+    mapped = ActorError.from_client_error(client_error)
+    assert type(mapped) is expected_cls
+    assert mapped.retryable is expected_retryable
+
+
+def test_from_client_error_unknown_exception_falls_back() -> None:
+    mapped = ActorError.from_client_error(RuntimeError('not a client error'))
+    assert type(mapped) is ActorError
+    assert mapped.retryable is False
+    assert 'not a client error' in str(mapped)
+
+
+def test_errors_exported_from_top_level() -> None:
+    for name in (
+        'ActorError',
+        'ActorRunError',
+        'ActorTimeoutError',
+        'ActorAuthenticationError',
+        'ActorChargeLimitExceededError',
+        'ActorInputValidationError',
+        'ActorRateLimitError',
+    ):
+        assert hasattr(apify, name)
+        assert name in apify.__all__
+        assert getattr(apify, name) is getattr(apify.errors, name)
diff --git a/website/docusaurus.config.js b/website/docusaurus.config.js
@@ -9,6 +9,7 @@ const GROUP_ORDER = [
     'Actor',
     'Charging',
     'Configuration',
+    'Errors',
     'Event data',
     'Event managers',
     'Events',
