feat: Add apify.errors domain-level error taxonomy

Author: vdusek

src/apify/__init__.py

@@ -17,6 +17,15 @@
 from apify._consts import ActorEnvVars, ApifyEnvVars
 from apify._proxy_configuration import ProxyConfiguration, ProxyInfo
 from apify._webhook import Webhook
+from apify.errors import (
+    ActorRunError,
+    ActorTimeoutError,
+    ApifyError,
+    AuthenticationError,
+    ChargeLimitExceededError,
+    InputValidationError,
+    RateLimitError,
+)
 from apify.events._types import ActorEventTypes
 
 __version__ = metadata.version('apify')
@@ -25,7 +34,12 @@
     'Actor',
     'ActorEnvVars',
     'ActorEventTypes',
+    'ActorRunError',
+    'ActorTimeoutError',
     'ApifyEnvVars',
+    'ApifyError',
+    'AuthenticationError',
+    'ChargeLimitExceededError',
     'Configuration',
     'Event',
     'EventAbortingData',
@@ -34,8 +48,10 @@
     'EventMigratingData',
     'EventPersistStateData',
     'EventSystemInfoData',
+    'InputValidationError',
     'ProxyConfiguration',
     'ProxyInfo',
+    'RateLimitError',
     'Request',
     'Webhook',
     'WebhookEventType',

src/apify/_utils.py

@@ -74,6 +74,7 @@ def is_running_in_ipython() -> bool:
     'Actor',
     'Charging',
     'Configuration',
+    'Errors',
     'Event data',
     'Event managers',
     'Events',

src/apify/errors.py

@@ -0,0 +1,170 @@
+"""Domain-level, machine-readable error taxonomy for the Apify SDK.
+
+These exceptions form a layer over the lower-level, HTTP-status-based exceptions raised by
+`apify_client`. Each error carries a stable, machine-readable `code` and a `retryable` flag so that
+automated (agent) callers can decide whether to retry, reformulate the input, pick another tool, or
+give up, without parsing human-readable log messages.
+
+The taxonomy is additive. Existing SDK methods keep raising the same `RuntimeError` / `ValueError`
+exceptions they always did. Where it makes sense, the domain errors subclass the relevant builtin
+(e.g. `InputValidationError` subclasses `ValueError`) so existing `except` handlers keep working.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from apify_client.errors import (
+    ForbiddenError,
+    InvalidRequestError,
+    ServerError,
+    UnauthorizedError,
+)
+from apify_client.errors import (
+    RateLimitError as _ClientRateLimitError,
+)
+
+from apify._utils import docs_group
+
+if TYPE_CHECKING:
+    from apify_client._models import Run
+
+
+@docs_group('Errors')
+class ApifyError(Exception):
+    """Base class for all domain-level Apify SDK errors.
+
+    Carries a machine-readable `code` and a `retryable` flag so automated (agent) callers can branch
+    on a failure without reading the human-readable message.
+    """
+
+    code: str = 'apify-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) -> ApifyError:
+        """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 `ApifyError`. The original exception is
+        not chained automatically; callers should use `raise ApifyError.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 AuthenticationError(str(error))
+        if isinstance(error, _ClientRateLimitError):
+            return RateLimitError(str(error))
+        if isinstance(error, ServerError):
+            return ApifyError(str(error), retryable=True)
+        if isinstance(error, InvalidRequestError):
+            return InputValidationError(str(error))
+        return ApifyError(str(error))
+
+
+@docs_group('Errors')
+class ActorRunError(ApifyError):
+    """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 InputValidationError(ApifyError, ValueError):
+    """Raised when input fails validation.
+
+    Subclasses `ValueError` so existing `except ValueError` handlers keep catching it.
+    """
+
+    code = 'input-validation-error'
+
+
+@docs_group('Errors')
+class ChargeLimitExceededError(ApifyError):
+    """Raised when an Actor run hits its configured maximum total charge (`max_total_charge_usd`)."""
+
+    code = 'charge-limit-exceeded'
+
+
+@docs_group('Errors')
+class AuthenticationError(ApifyError):
+    """Raised when an API request is unauthorized or forbidden (HTTP 401 / 403)."""
+
+    code = 'authentication-error'
+
+
+@docs_group('Errors')
+class RateLimitError(ApifyError):
+    """Raised when the Apify API rate limit is exceeded (HTTP 429). Retryable after a backoff."""
+
+    code = 'rate-limit-exceeded'
+    retryable = True
+
+
+__all__ = [
+    'ActorRunError',
+    'ActorTimeoutError',
+    'ApifyError',
+    'AuthenticationError',
+    'ChargeLimitExceededError',
+    'InputValidationError',
+    'RateLimitError',
+]