docs: Fix documentation mismatches with actual client behavior (#958)

Fixes 12 documentation issues found by an engineering audit, where docs,
examples, or docstrings contradict what the client actually does:

- The custom HTTP client guide example (`HttpxClient`) now raises
`ApifyApiError` for error responses instead of returning them raw, and
the guide documents this part of the `call` contract (resource clients
rely on it, e.g. to translate a 404 into a `None` return value).
- The streaming concepts page no longer claims all three streaming
methods yield a raw `impit.Response` — it now describes the actual
yielded value per method (`stream_record` yields a `dict` with the
response under `value`, `stream` and `stream_record` may yield `None`).
- The pagination concepts page no longer lists `ListOfRequests` among
page models exposing `total`/`offset`/`count`; it now explains its
cursor-based pagination via `next_cursor`.
- The logging formatter example no longer references `%(status_code)s`
(absent on most records, causing logging errors) and no longer attaches
a duplicate handler; the page notes which properties are present on
every record.
- The upgrading-to-v3 guide cross-links now include the site baseUrl
(`/api/client/python/...`), fixing 6 links that 404ed on the published
site.
- The conda instruction for the brotli extra installs `brotli-python`
(the Python bindings) instead of `brotli` (the C library).
- `RunClient.resurrect` docstrings cite the real `SUCCEEDED` status
instead of the nonexistent `FINISHED`.
- `wait_for_finish` docstrings in `RunClient` and `BuildClient` spell
the terminal status as `TIMED-OUT` (the real literal) instead of
`TIMED_OUT`.
- The quick-start page refers to the `Run` model's `default_dataset_id`
attribute instead of the v2-era run dictionary with `defaultDatasetId`.
- The README dataset example passes `fields` as `list[str]` per the
signature instead of a comma-separated string.
- The README quick-start examples handle the `Run | None` return of
`call()` instead of accessing attributes on a possible `None`.
- The timeouts concepts page states that `no_timeout` is capped at 24
hours by the default client instead of claiming it disables the timeout
entirely.

*✍️ Drafted by Claude Code*

Author: vdusek

README.md

@@ -79,6 +79,8 @@ client = ApifyClient('MY-APIFY-TOKEN')
 run = client.actor('apify/hello-world').call(
     run_input={'message': 'Hello, Apify!'},
 )
+if run is None:
+    raise RuntimeError('Actor run was not found.')
 
 # Iterate items from the run's default dataset.
 for item in client.dataset(run.default_dataset_id).iterate_items():
@@ -99,6 +101,8 @@ async def main() -> None:
     run = await client.actor('apify/hello-world').call(
         run_input={'message': 'Hello, Apify!'},
     )
+    if run is None:
+        raise RuntimeError('Actor run was not found.')
 
     # Iterate items from the run's default dataset.
     async for item in client.dataset(run.default_dataset_id).iterate_items():
@@ -158,7 +162,7 @@ record = store.get_record('greeting')
 ### Iterate dataset items with automatic pagination
 
 ```python
-for item in client.dataset('DATASET-ID').iterate_items(fields='title,url'):
+for item in client.dataset('DATASET-ID').iterate_items(fields=['title', 'url']):
     process(item)
 ```
 

docs/01_introduction/index.mdx

@@ -56,11 +56,17 @@ For better request-body compression, opt in to `brotli`, which compresses better
     </TabItem>
     <TabItem value="conda-forge" label="conda-forge">
         ```bash
-        conda install conda-forge::apify-client conda-forge::brotli
+        conda install conda-forge::apify-client conda-forge::brotli-python
         ```
     </TabItem>
 </Tabs>
 
+:::note Extras on conda-forge
+
+Conda doesn't support optional extras. On conda-forge, install the `brotli-python` package directly alongside the client. It provides the same `brotli` module as the PyPI extra.
+
+:::
+
 For details, see [HTTP compression](../02_concepts/13_http_compression.mdx).
 
 ## Quick example

docs/01_introduction/quick-start.mdx

@@ -65,7 +65,7 @@ To define the Actor's input, pass a dictionary to the <ApiLink to="class/ActorCl
 
 ## Step 3: Get results from the dataset
 
-To get the results from the dataset, call the <ApiLink to="class/DatasetClient">`apify_client.dataset()`</ApiLink> method with the dataset ID, then call <ApiLink to="class/DatasetClient#list_items">`list_items()`</ApiLink> to retrieve the data. You can get the dataset ID from the Actor's run dictionary (represented by `defaultDatasetId`).
+To get the results from the dataset, call the <ApiLink to="class/DatasetClient">`apify_client.dataset()`</ApiLink> method with the dataset ID, then call <ApiLink to="class/DatasetClient#list_items">`list_items()`</ApiLink> to retrieve the data. You can get the dataset ID from the `default_dataset_id` attribute of the <ApiLink to="class/Run">`Run`</ApiLink> object returned by `call()`.
 
 <Tabs>
     <TabItem value="AsyncExample" label="Async client" default>

docs/02_concepts/06_logging.mdx

@@ -20,12 +20,12 @@ The library logs useful debug information to the `apify_client` logger whenever
 The log records include additional properties, provided via the extra argument, which can be helpful for debugging. Some of these properties are:
 
 - `attempt` - Number of retry attempts for the request.
-- `status_code` - HTTP status code of the response.
+- `status_code` - HTTP status code of the response. Only present on records about a request's outcome.
 - `url` - URL of the API endpoint being called.
 - `client_method` - Method name of the client that initiated the request.
 - `resource_id` - Identifier of the resource being accessed.
 
-To display these additional properties in the log output, you need to use a custom log formatter. Here's a basic example:
+To display these additional properties in the log output, you need to use a custom log formatter. Reference only the properties present on every record, since a `%`-style formatter raises an error for records that lack a referenced property. Here's a basic example:
 
 <CodeBlock className="language-python">
     {LoggingFormatterExample}

docs/02_concepts/08_pagination.mdx

@@ -17,15 +17,15 @@ import IterateItemsSyncExample from '!!raw-loader!./code/08_iterate_items_sync.p
 import IterateCollectionAsyncExample from '!!raw-loader!./code/08_iterate_collection_async.py';
 import IterateCollectionSyncExample from '!!raw-loader!./code/08_iterate_collection_sync.py';
 
-Most methods named `list` or `list_something` in the Apify client return a page model — a [Pydantic](https://docs.pydantic.dev/latest/) model such as <ApiLink to="class/ListOfActors">`ListOfActors`</ApiLink>, <ApiLink to="class/ListOfDatasets">`ListOfDatasets`</ApiLink>, or <ApiLink to="class/ListOfRequests">`ListOfRequests`</ApiLink>. Unstructured dataset items use the <ApiLink to="class/DatasetItemsPage">`DatasetItemsPage`</ApiLink> dataclass instead. All page models share a consistent interface for working with paginated data and expose the following fields:
+Most methods named `list` or `list_something` in the Apify client return a page model — a [Pydantic](https://docs.pydantic.dev/latest/) model such as <ApiLink to="class/ListOfActors">`ListOfActors`</ApiLink> or <ApiLink to="class/ListOfDatasets">`ListOfDatasets`</ApiLink>. Unstructured dataset items use the <ApiLink to="class/DatasetItemsPage">`DatasetItemsPage`</ApiLink> dataclass instead. All page models share a consistent interface for working with paginated data and expose the following fields:
 
 - `items` - The main results you're looking for.
 - `total` - The total number of items available.
 - `offset` - The starting point of the current page.
 - `count` - The number of items in the current page.
 - `limit` - The maximum number of items per page.
 
-Some methods, such as `list_keys` or `list_head`, paginate differently. Regardless, the primary results are always stored under the `items` field, and the `limit` field can be used to control the number of results returned.
+Some methods paginate differently. For example, <ApiLink to="class/RequestQueueClient#list_requests">`RequestQueueClient.list_requests`</ApiLink> returns a cursor-based <ApiLink to="class/ListOfRequests">`ListOfRequests`</ApiLink> without the `total`, `offset`, and `count` fields. To fetch the next page, pass its `next_cursor` value back as the `cursor` parameter. Other examples include `list_keys` and `list_head`. Regardless, the primary results are always stored under the `items` field, and the `limit` field can be used to control the number of results returned.
 
 The following example shows how to fetch all items from a dataset using pagination:
 

docs/02_concepts/09_streaming.mdx

@@ -17,11 +17,11 @@ Certain resources, such as dataset items, key-value store records, and logs, sup
 
 Supported streaming methods:
 
-- <ApiLink to="class/DatasetClient#stream_items">`DatasetClient.stream_items`</ApiLink> - Stream dataset items incrementally.
-- <ApiLink to="class/KeyValueStoreClient#stream_record">`KeyValueStoreClient.stream_record`</ApiLink> - Stream key-value store records as raw data.
-- <ApiLink to="class/LogClient#stream">`LogClient.stream`</ApiLink> - Stream logs in real time.
+- <ApiLink to="class/DatasetClient#stream_items">`DatasetClient.stream_items`</ApiLink> - Stream dataset items incrementally. Yields a raw streaming <ApiLink to="class/HttpResponse">`HttpResponse`</ApiLink>.
+- <ApiLink to="class/KeyValueStoreClient#stream_record">`KeyValueStoreClient.stream_record`</ApiLink> - Stream a key-value store record as raw data. Yields a `dict` with the `key`, `value`, and `content_type` fields, where `value` holds the raw streaming response, or `None` when the record doesn't exist.
+- <ApiLink to="class/LogClient#stream">`LogClient.stream`</ApiLink> - Stream logs in real time. Yields a raw streaming <ApiLink to="class/HttpResponse">`HttpResponse`</ApiLink>, or `None` when the log doesn't exist.
 
-These methods return a raw, context-managed `impit.Response` object. The response must be consumed within a with block to ensure that the connection is closed automatically, preventing memory leaks or unclosed connections.
+All three methods are context managers. Consume the streamed data within a `with` block to ensure that the connection is closed automatically, preventing memory leaks or unclosed connections.
 
 The following example shows how to stream the logs of an Actor run incrementally:
 

docs/02_concepts/11_timeouts.mdx

@@ -19,7 +19,7 @@ The Apify client uses a tiered timeout system to set appropriate time limits for
 | `short` | 5 seconds | Fast CRUD operations (get, update, delete) |
 | `medium` | 30 seconds | Batch, list, and data transfer operations |
 | `long` | 360 seconds | Long-polling, streaming, and heavy operations |
-| `no_timeout` | — | Disables the timeout entirely |
+| `no_timeout` | — | Effectively disables the timeout (the default client caps it at 24 hours) |
 
 Every client method has a pre-assigned tier that matches the expected duration of the underlying API call. You generally don't need to change these unless you're working with unusually large payloads or slow network conditions.
 
@@ -53,7 +53,7 @@ client.dataset('id').list_items(timeout=timedelta(seconds=120))
 # Switch to a different tier.
 client.dataset('id').list_items(timeout='long')
 
-# Disable the timeout entirely.
+# Effectively disable the timeout (capped at 24 hours by the default client).
 client.dataset('id').list_items(timeout='no_timeout')
 ```
 

docs/02_concepts/code/06_logging_formatter.py

@@ -1,15 +1,17 @@
 import logging
 
-# Configure the Apify client logger
-apify_client_logger = logging.getLogger('apify_client')
-apify_client_logger.setLevel(logging.DEBUG)
-apify_client_logger.addHandler(logging.StreamHandler())
-
-# Create a custom logging formatter
+# Create a custom logging formatter. Reference only the properties present
+# on every record. Properties attached to some records only, such as
+# `status_code`, would raise an error for the records that lack them.
 formatter = logging.Formatter(
     '%(asctime)s - %(name)s - %(levelname)s - %(message)s - '
-    '%(attempt)s - %(status_code)s - %(url)s'
+    '%(client_method)s - %(attempt)s - %(url)s'
 )
+
 handler = logging.StreamHandler()
 handler.setFormatter(formatter)
+
+# Configure the Apify client logger to use the custom formatter
+apify_client_logger = logging.getLogger('apify_client')
+apify_client_logger.setLevel(logging.DEBUG)
 apify_client_logger.addHandler(handler)

docs/03_guides/05_custom_http_client.mdx

@@ -33,6 +33,8 @@ The `call` method receives parameters like `method`, `url`, `headers`, `params`,
 
 A convenient property of HTTPX is that its `httpx.Response` object already satisfies the <ApiLink to="class/HttpResponse">`HttpResponse`</ApiLink> protocol, so you can return it directly without wrapping.
 
+One part of the contract isn't visible in the method signature: `call` must raise <ApiLink to="class/ApifyApiError">`ApifyApiError`</ApiLink> for error responses instead of returning them. The resource clients rely on that error to work correctly. For example, `get` methods translate a 404 raised this way into a `None` return value, and user code handling `ApifyApiError` keeps working.
+
 <Tabs>
     <TabItem value="AsyncExample" label="Async client" default>
         <CodeBlock className="language-python">

docs/03_guides/code/05_custom_http_client_async.py

@@ -1,11 +1,13 @@
 from __future__ import annotations
 
 import asyncio
+from http import HTTPStatus
 from typing import TYPE_CHECKING, Any
 
 import httpx
 
 from apify_client import ApifyClientAsync
+from apify_client.errors import ApifyApiError
 from apify_client.http_clients import HttpClientAsync, HttpResponse
 
 if TYPE_CHECKING:
@@ -39,9 +41,7 @@ async def call(
         # with the per-request ones.
         headers = self._merge_headers(self._headers, headers)
 
-        # httpx.Response satisfies the HttpResponse protocol,
-        # so it can be returned directly.
-        return await self._client.request(
+        response = await self._client.request(
             method=method,
             url=url,
             headers=headers,
@@ -51,6 +51,16 @@ async def call(
             timeout=timeout_secs,
         )
 
+        # Raising `ApifyApiError` for error responses is part of the `call`
+        # contract. The resource clients rely on it, e.g. to translate a 404
+        # into a `None` return value of `get` methods.
+        if response.status_code >= HTTPStatus.BAD_REQUEST:
+            raise ApifyApiError(response, attempt=1, method=method)
+
+        # httpx.Response satisfies the HttpResponse protocol,
+        # so it can be returned directly.
+        return response
+
 
 async def main() -> None:
     client = ApifyClientAsync.with_custom_http_client(