feat: Introduce tiered timeout system with per-endpoint configuration

docs/02_concepts/code/05_retries_async.py

@@ -8,7 +8,10 @@
 async def main() -> None:
     apify_client = ApifyClientAsync(
         token=TOKEN,
-        max_retries=8,
+        max_retries=4,
         min_delay_between_retries=timedelta(milliseconds=500),
-        timeout=timedelta(seconds=360),
+        timeout_short=timedelta(seconds=5),
+        timeout_medium=timedelta(seconds=30),
+        timeout_long=timedelta(seconds=360),
+        timeout_max=timedelta(seconds=360),
     )

docs/02_concepts/code/05_retries_sync.py

@@ -8,7 +8,10 @@
 def main() -> None:
     apify_client = ApifyClient(
         token=TOKEN,
-        max_retries=8,
+        max_retries=4,
         min_delay_between_retries=timedelta(milliseconds=500),
-        timeout=timedelta(seconds=360),
+        timeout_short=timedelta(seconds=5),
+        timeout_medium=timedelta(seconds=30),
+        timeout_long=timedelta(seconds=360),
+        timeout_max=timedelta(seconds=360),
     )

src/apify_client/__init__.py

@@ -8,6 +8,7 @@
     ImpitHttpClient,
     ImpitHttpClientAsync,
 )
+from ._types import Timeout
 
 __version__ = metadata.version('apify-client')
 
@@ -19,5 +20,6 @@
     'HttpResponse',
     'ImpitHttpClient',
     'ImpitHttpClientAsync',
+    'Timeout',
     '__version__',
 ]

src/apify_client/_apify_client.py

@@ -9,7 +9,10 @@
     DEFAULT_API_URL,
     DEFAULT_MAX_RETRIES,
     DEFAULT_MIN_DELAY_BETWEEN_RETRIES,
-    DEFAULT_TIMEOUT,
+    DEFAULT_TIMEOUT_LONG,
+    DEFAULT_TIMEOUT_MAX,
+    DEFAULT_TIMEOUT_MEDIUM,
+    DEFAULT_TIMEOUT_SHORT,
 )
 from apify_client._docs import docs_group
 from apify_client._http_clients import HttpClient, HttpClientAsync, ImpitHttpClient, ImpitHttpClientAsync
@@ -114,7 +117,10 @@ def __init__(
         api_public_url: str | None = DEFAULT_API_URL,
         max_retries: int = DEFAULT_MAX_RETRIES,
         min_delay_between_retries: timedelta = DEFAULT_MIN_DELAY_BETWEEN_RETRIES,
-        timeout: timedelta = DEFAULT_TIMEOUT,
+        timeout_short: timedelta = DEFAULT_TIMEOUT_SHORT,
+        timeout_medium: timedelta = DEFAULT_TIMEOUT_MEDIUM,
+        timeout_long: timedelta = DEFAULT_TIMEOUT_LONG,
+        timeout_max: timedelta = DEFAULT_TIMEOUT_MAX,
         headers: dict[str, str] | None = None,
     ) -> None:
         """Initialize the Apify API client.
@@ -132,7 +138,10 @@ def __init__(
             max_retries: How many times to retry a failed request at most.
             min_delay_between_retries: How long will the client wait between retrying requests
                 (increases exponentially from this value).
-            timeout: The socket timeout of the HTTP requests sent to the Apify API.
+            timeout_short: Default timeout for short-duration API operations (simple CRUD operations, ...).
+            timeout_medium: Default timeout for medium-duration API operations (batch operations, listing, ...).
+            timeout_long: Default timeout for long-duration API operations (long-polling, streaming, ...).
+            timeout_max: Maximum timeout cap for exponential timeout growth across retries.
             headers: Additional HTTP headers to include in all API requests.
         """
         # We need to do this because of mocking in tests and default mutable arguments.
@@ -191,7 +200,10 @@ def __init__(
         # Configuration for the default HTTP client (used if a custom client is not provided).
         self._max_retries = max_retries
         self._min_delay_between_retries = min_delay_between_retries
-        self._timeout = timeout
+        self._timeout_short = timeout_short
+        self._timeout_medium = timeout_medium
+        self._timeout_long = timeout_long
+        self._timeout_max = timeout_max
         self._headers = headers
 
     @classmethod
@@ -249,7 +261,10 @@ def http_client(self) -> HttpClient:
         if self._http_client is None:
             self._http_client = ImpitHttpClient(
                 token=self._token,
-                timeout=self._timeout,
+                timeout_short=self._timeout_short,
+                timeout_medium=self._timeout_medium,
+                timeout_long=self._timeout_long,
+                timeout_max=self._timeout_max,
                 max_retries=self._max_retries,
                 min_delay_between_retries=self._min_delay_between_retries,
                 statistics=self._statistics,
@@ -455,7 +470,10 @@ def __init__(
         api_public_url: str | None = DEFAULT_API_URL,
         max_retries: int = DEFAULT_MAX_RETRIES,
         min_delay_between_retries: timedelta = DEFAULT_MIN_DELAY_BETWEEN_RETRIES,
-        timeout: timedelta = DEFAULT_TIMEOUT,
+        timeout_short: timedelta = DEFAULT_TIMEOUT_SHORT,
+        timeout_medium: timedelta = DEFAULT_TIMEOUT_MEDIUM,
+        timeout_long: timedelta = DEFAULT_TIMEOUT_LONG,
+        timeout_max: timedelta = DEFAULT_TIMEOUT_MAX,
         headers: dict[str, str] | None = None,
     ) -> None:
         """Initialize the Apify API client.
@@ -473,7 +491,10 @@ def __init__(
             max_retries: How many times to retry a failed request at most.
             min_delay_between_retries: How long will the client wait between retrying requests
                 (increases exponentially from this value).
-            timeout: The socket timeout of the HTTP requests sent to the Apify API.
+            timeout_short: Default timeout for short-duration API operations (simple CRUD operations, ...).
+            timeout_medium: Default timeout for medium-duration API operations (batch operations, listing, ...).
+            timeout_long: Default timeout for long-duration API operations (long-polling, streaming, ...).
+            timeout_max: Maximum timeout cap for exponential timeout growth across retries.
             headers: Additional HTTP headers to include in all API requests.
         """
         # We need to do this because of mocking in tests and default mutable arguments.
@@ -532,7 +553,10 @@ def __init__(
         # Configuration for the default HTTP client (used if a custom client is not provided).
         self._max_retries = max_retries
         self._min_delay_between_retries = min_delay_between_retries
-        self._timeout = timeout
+        self._timeout_short = timeout_short
+        self._timeout_medium = timeout_medium
+        self._timeout_long = timeout_long
+        self._timeout_max = timeout_max
         self._headers = headers
 
     @classmethod
@@ -590,7 +614,10 @@ def http_client(self) -> HttpClientAsync:
         if self._http_client is None:
             self._http_client = ImpitHttpClientAsync(
                 token=self._token,
-                timeout=self._timeout,
+                timeout_short=self._timeout_short,
+                timeout_medium=self._timeout_medium,
+                timeout_long=self._timeout_long,
+                timeout_max=self._timeout_max,
                 max_retries=self._max_retries,
                 min_delay_between_retries=self._min_delay_between_retries,
                 statistics=self._statistics,

src/apify_client/_consts.py

@@ -1,25 +1,28 @@
 from __future__ import annotations
 
 from datetime import timedelta
-from typing import Any
 
 from apify_client._models import ActorJobStatus
 
-JsonSerializable = str | int | float | bool | None | dict[str, Any] | list[Any]
-"""Type for representing json-serializable values. It's close enough to the real thing supported by json.parse.
-It was suggested in a discussion with (and approved by) Guido van Rossum, so I'd consider it correct enough.
-"""
-
 DEFAULT_API_URL = 'https://api.apify.com'
 """Default base URL for the Apify API."""
 
 API_VERSION = 'v2'
 """Current Apify API version."""
 
-DEFAULT_TIMEOUT = timedelta(seconds=360)
-"""Default request timeout."""
+DEFAULT_TIMEOUT_SHORT = timedelta(seconds=5)
+"""Default timeout for fast CRUD operations (e.g., get, update, delete)."""
+
+DEFAULT_TIMEOUT_MEDIUM = timedelta(seconds=30)
+"""Default timeout for batch, list, and data transfer operations."""
+
+DEFAULT_TIMEOUT_LONG = timedelta(seconds=360)
+"""Default timeout for long-polling, streaming, and other heavy operations."""
 
-DEFAULT_MAX_RETRIES = 8
+DEFAULT_TIMEOUT_MAX = timedelta(seconds=360)
+"""Default maximum timeout cap for individual API requests (limits exponential growth)."""
+
+DEFAULT_MAX_RETRIES = 4
 """Default maximum number of retries for failed requests."""
 
 DEFAULT_MIN_DELAY_BETWEEN_RETRIES = timedelta(milliseconds=500)
@@ -31,12 +34,6 @@
 DEFAULT_WAIT_WHEN_JOB_NOT_EXIST = timedelta(seconds=3)
 """How long to wait for a job to exist before giving up."""
 
-FAST_OPERATION_TIMEOUT = timedelta(seconds=5)
-"""Timeout for fast, idempotent operations (e.g., GET, DELETE)."""
-
-STANDARD_OPERATION_TIMEOUT = timedelta(seconds=30)
-"""Timeout for operations that may take longer (e.g., list operations, batch operations)."""
-
 TERMINAL_STATUSES = frozenset(
     {
         ActorJobStatus.SUCCEEDED,

src/apify_client/_http_clients/_base.py

@@ -10,15 +10,22 @@
 from typing import TYPE_CHECKING, Any, Protocol, runtime_checkable
 from urllib.parse import urlencode
 
-from apify_client._consts import DEFAULT_MAX_RETRIES, DEFAULT_MIN_DELAY_BETWEEN_RETRIES, DEFAULT_TIMEOUT
+from apify_client._consts import (
+    DEFAULT_MAX_RETRIES,
+    DEFAULT_MIN_DELAY_BETWEEN_RETRIES,
+    DEFAULT_TIMEOUT_LONG,
+    DEFAULT_TIMEOUT_MAX,
+    DEFAULT_TIMEOUT_MEDIUM,
+    DEFAULT_TIMEOUT_SHORT,
+)
 from apify_client._docs import docs_group
 from apify_client._statistics import ClientStatistics
 from apify_client._utils import to_seconds
 
 if TYPE_CHECKING:
     from collections.abc import AsyncIterator, Iterator, Mapping
 
-    from apify_client._consts import JsonSerializable
+    from apify_client._types import JsonSerializable, Timeout
 
 
 @docs_group('HTTP clients')
@@ -85,7 +92,10 @@ def __init__(
         self,
         *,
         token: str | None = None,
-        timeout: timedelta = DEFAULT_TIMEOUT,
+        timeout_short: timedelta = DEFAULT_TIMEOUT_SHORT,
+        timeout_medium: timedelta = DEFAULT_TIMEOUT_MEDIUM,
+        timeout_long: timedelta = DEFAULT_TIMEOUT_LONG,
+        timeout_max: timedelta = DEFAULT_TIMEOUT_MAX,
         max_retries: int = DEFAULT_MAX_RETRIES,
         min_delay_between_retries: timedelta = DEFAULT_MIN_DELAY_BETWEEN_RETRIES,
         statistics: ClientStatistics | None = None,
@@ -95,13 +105,19 @@ def __init__(
 
         Args:
             token: Apify API token for authentication.
-            timeout: Request timeout.
+            timeout_short: Default timeout for short-duration API operations (simple CRUD operations, ...).
+            timeout_medium: Default timeout for medium-duration API operations (batch operations, listing, ...).
+            timeout_long: Default timeout for long-duration API operations (long-polling, streaming, ...).
+            timeout_max: Maximum timeout cap for exponential timeout growth across retries.
             max_retries: Maximum number of retries for failed requests.
             min_delay_between_retries: Minimum delay between retries.
             statistics: Statistics tracker for API calls. Created automatically if not provided.
             headers: Additional HTTP headers to include in all requests.
         """
-        self._timeout = timeout
+        self._timeout_short = timeout_short
+        self._timeout_medium = timeout_medium
+        self._timeout_long = timeout_long
+        self._timeout_max = timeout_max
         self._max_retries = max_retries
         self._min_delay_between_retries = min_delay_between_retries
         self._statistics = statistics or ClientStatistics()
@@ -149,6 +165,34 @@ def _parse_params(params: dict[str, Any] | None) -> dict[str, Any] | None:
 
         return parsed_params
 
+    def _compute_timeout(self, timeout: Timeout, attempt: int) -> int | float | None:
+        """Resolve a timeout tier and compute the timeout for a request attempt with exponential increase.
+
+        For `'no_timeout'`, returns `None`. For tier literals and explicit `timedelta` values, doubles the timeout
+        with each attempt but caps at `timeout_max`.
+
+        Args:
+            timeout: The timeout specification to resolve (tier literal or explicit `timedelta`).
+            attempt: Current attempt number (1-indexed).
+
+        Returns:
+            Timeout in seconds, or `None` for `'no_timeout'`.
+        """
+        if timeout == 'no_timeout':
+            return None
+
+        if timeout == 'short':
+            resolved = self._timeout_short
+        elif timeout == 'medium':
+            resolved = self._timeout_medium
+        elif timeout == 'long':
+            resolved = self._timeout_long
+        else:
+            resolved = timeout
+
+        new_timeout = min(resolved * (2 ** (attempt - 1)), self._timeout_max)
+        return to_seconds(new_timeout)
+
     def _prepare_request_call(
         self,
         headers: dict[str, str] | None = None,
@@ -192,12 +236,6 @@ def _build_url_with_params(self, url: str, params: dict[str, Any] | None = None)
 
         return f'{url}?{query_string}'
 
-    def _calculate_timeout(self, attempt: int, timeout: timedelta | None = None) -> float:
-        """Calculate timeout for a request attempt with exponential increase, bounded by client timeout."""
-        timeout_secs = to_seconds(timeout or self._timeout)
-        client_timeout_secs = to_seconds(self._timeout)
-        return min(client_timeout_secs, timeout_secs * 2 ** (attempt - 1))
-
 
 @docs_group('HTTP clients')
 class HttpClient(HttpClientBase, ABC):
@@ -219,7 +257,7 @@ def call(
         data: str | bytes | bytearray | None = None,
         json: Any = None,
         stream: bool | None = None,
-        timeout: timedelta | None = None,
+        timeout: Timeout = 'medium',
     ) -> HttpResponse:
         """Make an HTTP request.
 
@@ -231,7 +269,9 @@ def call(
             data: Raw request body data. Cannot be used together with json.
             json: JSON-serializable data for the request body. Cannot be used together with data.
             stream: Whether to stream the response body.
-            timeout: Timeout for this specific request.
+            timeout: Timeout for the API HTTP request. Use `short`, `medium`, or `long` tier literals for
+                preconfigured timeouts. A `timedelta` overrides it for this call, and `no_timeout` disables
+                the timeout entirely.
 
         Returns:
             The HTTP response object.
@@ -240,7 +280,6 @@ def call(
             ApifyApiError: If the request fails after all retries or returns a non-retryable error status.
             ValueError: If both json and data are provided.
         """
-        ...
 
 
 @docs_group('HTTP clients')
@@ -262,7 +301,7 @@ async def call(
         data: str | bytes | bytearray | None = None,
         json: Any = None,
         stream: bool | None = None,
-        timeout: timedelta | None = None,
+        timeout: Timeout = 'medium',
     ) -> HttpResponse:
         """Make an HTTP request.
 
@@ -274,7 +313,9 @@ async def call(
             data: Raw request body data. Cannot be used together with json.
             json: JSON-serializable data for the request body. Cannot be used together with data.
             stream: Whether to stream the response body.
-            timeout: Timeout for this specific request.
+            timeout: Timeout for the API HTTP request. Use `short`, `medium`, or `long` tier literals for
+                preconfigured timeouts. A `timedelta` overrides it for this call, and `no_timeout` disables
+                the timeout entirely.
 
         Returns:
             The HTTP response object.
@@ -283,4 +324,3 @@ async def call(
             ApifyApiError: If the request fails after all retries or returns a non-retryable error status.
             ValueError: If both json and data are provided.
         """
-        ...