docs: Clarify timeout_max honors a base timeout larger than the cap

Author: vdusek

docs/02_concepts/11_timeouts.mdx

@@ -25,7 +25,7 @@ Every client method has a pre-assigned tier that matches the expected duration o
 
 ## Configuring default timeouts
 
-You can override the default values for each tier in the <ApiLink to="class/ApifyClient">`ApifyClient`</ApiLink> or <ApiLink to="class/ApifyClientAsync">`ApifyClientAsync`</ApiLink> constructor. The `timeout_max` parameter sets an upper cap on the timeout for any individual API request, limiting exponential growth during retries.
+You can override the default values for each tier in the <ApiLink to="class/ApifyClient">`ApifyClient`</ApiLink> or <ApiLink to="class/ApifyClientAsync">`ApifyClientAsync`</ApiLink> constructor. The `timeout_max` parameter caps the exponential timeout growth during retries. A base timeout that's already larger than `timeout_max`, whether an explicit `timedelta` or a tier configured above the cap, is honored as-is.
 
 <Tabs>
     <TabItem value="AsyncExample" label="Async client" default>

src/apify_client/_apify_client.py

@@ -146,7 +146,7 @@ def __init__(
             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.
+            timeout_max: Caps exponential timeout growth across retries. A larger base timeout is honored, not clamped.
             headers: Additional HTTP headers to include in all API requests.
             compression: Compression algorithm for request bodies. Pass a string literal to select an algorithm,
                 or an `HttpCompressor` instance for finer-grained control.
@@ -508,7 +508,7 @@ def __init__(
             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.
+            timeout_max: Caps exponential timeout growth across retries. A larger base timeout is honored, not clamped.
             headers: Additional HTTP headers to include in all API requests.
             compression: Compression algorithm for request bodies. Pass a string literal to select an algorithm,
                 or an `HttpCompressor` instance for finer-grained control.

src/apify_client/http_clients/_base.py

@@ -110,7 +110,7 @@ def __init__(
             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.
+            timeout_max: Caps exponential timeout growth across retries. A larger base timeout is honored, not clamped.
             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.

src/apify_client/http_clients/_impit.py

@@ -83,7 +83,7 @@ def __init__(
             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.
+            timeout_max: Caps exponential timeout growth across retries. A larger base timeout is honored, not clamped.
             max_retries: Maximum number of retry attempts for failed requests.
             min_delay_between_retries: Minimum delay between retries (increases exponentially with each attempt).
             statistics: Statistics tracker for API calls. Created automatically if not provided.
@@ -332,7 +332,7 @@ def __init__(
             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.
+            timeout_max: Caps exponential timeout growth across retries. A larger base timeout is honored, not clamped.
             max_retries: Maximum number of retry attempts for failed requests.
             min_delay_between_retries: Minimum delay between retries (increases exponentially with each attempt).
             statistics: Statistics tracker for API calls. Created automatically if not provided.

tests/unit/test_client_timeouts.py

@@ -158,6 +158,15 @@ def test_compute_timeout_explicit_timedelta_above_max_not_clamped() -> None:
     assert client._compute_timeout(timedelta(minutes=30), attempt=2) == 1800.0
 
 
+def test_compute_timeout_tier_above_max_not_clamped() -> None:
+    """Test a configured tier larger than timeout_max is honored, not clamped."""
+    client = ImpitHttpClient(timeout_long=timedelta(seconds=600), timeout_max=timedelta(seconds=360))
+
+    assert client._compute_timeout('long', attempt=1) == 600.0
+    # Exponential growth stays bounded by the tier's base value itself.
+    assert client._compute_timeout('long', attempt=2) == 600.0
+
+
 async def test_dynamic_timeout_async_client(monkeypatch: pytest.MonkeyPatch) -> None:
     """Tests timeout values for request with retriable errors.