docs: document v3 error subclasses, fix pagination, flag internal modules (#801)

## Summary

Addresses review feedback on the v3 docs:

- **Error handling concept page** — adds an *Error subclasses* section
with the status-to-class table and updates the code examples to
demonstrate catching a specific subclass (`NotFoundError`) alongside the
generic `ApifyApiError`.
- **Pagination concept page** — removes stale references to the v2
`ListPage` class; list methods now return Pydantic page models like
`ListOfActors` / `ListOfDatasets` / `ListOfRequests` (or the
`DatasetItemsPage` dataclass for unstructured items).
- **v3 upgrade guide** — adds a warning that `apify_client._models`,
`apify_client._typeddicts`, and `apify_client._literals` are internal
modules with no public-API stability guarantee, and replaces the
duplicated error-subclass table with a cross-link to the concept page so
the mapping has a single source of truth.

Author: vdusek

docs/02_concepts/04_error_handling.mdx

@@ -14,6 +14,22 @@ import ErrorSyncExample from '!!raw-loader!./code/04_error_sync.py';
 
 When you use the Apify client, it automatically extracts all relevant data from the endpoint and returns it in the expected format. Date strings, for instance, are seamlessly converted to Python `datetime.datetime` objects. If an error occurs, the client raises an <ApiLink to="class/ApifyApiError">`ApifyApiError`</ApiLink>. This exception wraps the raw JSON errors returned by the API and provides additional context, making it easier to debug any issues that arise.
 
+## Error subclasses
+
+The Apify client provides dedicated error subclasses based on the HTTP status code of the failed response, so you can branch on error kind without inspecting `status_code` or `type`:
+
+| Status | Subclass |
+|---|---|
+| 400 | <ApiLink to="class/InvalidRequestError">`InvalidRequestError`</ApiLink> |
+| 401 | <ApiLink to="class/UnauthorizedError">`UnauthorizedError`</ApiLink> |
+| 403 | <ApiLink to="class/ForbiddenError">`ForbiddenError`</ApiLink> |
+| 404 | <ApiLink to="class/NotFoundError">`NotFoundError`</ApiLink> |
+| 409 | <ApiLink to="class/ConflictError">`ConflictError`</ApiLink> |
+| 429 | <ApiLink to="class/RateLimitError">`RateLimitError`</ApiLink> |
+| 5xx | <ApiLink to="class/ServerError">`ServerError`</ApiLink> |
+
+All subclasses inherit from <ApiLink to="class/ApifyApiError">`ApifyApiError`</ApiLink>, so an existing `except ApifyApiError` handler still catches every API error. Catch a specific subclass when you want to react differently to, for example, a missing resource or a rate-limit:
+
 <Tabs>
     <TabItem value="AsyncExample" label="Async client" default>
         <CodeBlock className="language-python">

docs/02_concepts/08_pagination.mdx

@@ -1,7 +1,7 @@
 ---
 id: pagination
 title: Pagination
-description: Paginate through large result sets using ListPage or generator-based iteration.
+description: Paginate through large result sets using page models or generator-based iteration.
 ---
 
 import Tabs from '@theme/Tabs';
@@ -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 <ApiLink to="class/ListPage">`ListPage`</ApiLink>  object. This object provides a consistent interface for working with paginated data and includes the following properties:
+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:
 
 - `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 property, and the limit property can be used to control the number of results returned.
+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.
 
 The following example shows how to fetch all items from a dataset using pagination:
 
@@ -42,7 +42,7 @@ The following example shows how to fetch all items from a dataset using paginati
     </TabItem>
 </Tabs>
 
-The <ApiLink to="class/ListPage">`ListPage`</ApiLink> interface offers several key benefits. Its consistent structure ensures predictable results for most `list` methods, providing a uniform way to work with paginated data. It also offers flexibility, allowing you to customize the `limit` and `offset` parameters to control data fetching according to your needs. Additionally, it provides scalability, enabling you to efficiently handle large datasets through pagination. This approach ensures efficient data retrieval while keeping memory usage under control, making it ideal for managing and processing large collections.
+The page model interface offers several key benefits. Its consistent structure ensures predictable results for most `list` methods, providing a uniform way to work with paginated data. It also offers flexibility, allowing you to customize the `limit` and `offset` parameters to control data fetching according to your needs. Additionally, it provides scalability, enabling you to efficiently handle large datasets through pagination. This approach ensures efficient data retrieval while keeping memory usage under control, making it ideal for managing and processing large collections.
 
 ## Generator-based iteration
 

docs/02_concepts/code/04_error_async.py

@@ -1,7 +1,7 @@
 import asyncio
 
 from apify_client import ApifyClientAsync
-from apify_client.errors import ApifyApiError
+from apify_client.errors import ApifyApiError, NotFoundError
 
 TOKEN = 'MY-APIFY-TOKEN'
 
@@ -13,9 +13,15 @@ async def main() -> None:
         # Try to list items from a non-existing dataset.
         dataset_client = apify_client.dataset('non-existing-dataset-id')
         dataset_items = (await dataset_client.list_items()).items
+    except NotFoundError:
+        # 404 — branch on a specific subclass when you want to react to it.
+        dataset_items = []
     except ApifyApiError as err:
-        # The client raises ApifyApiError for API errors.
+        # Catch-all for every other API error.
         print(f'API error: {err}')
+        dataset_items = []
+
+    print(f'Fetched {len(dataset_items)} items.')
 
 
 if __name__ == '__main__':

docs/02_concepts/code/04_error_sync.py

@@ -1,5 +1,5 @@
 from apify_client import ApifyClient
-from apify_client.errors import ApifyApiError
+from apify_client.errors import ApifyApiError, NotFoundError
 
 TOKEN = 'MY-APIFY-TOKEN'
 
@@ -11,9 +11,15 @@ def main() -> None:
         # Try to list items from a non-existing dataset.
         dataset_client = apify_client.dataset('non-existing-dataset-id')
         dataset_items = dataset_client.list_items().items
+    except NotFoundError:
+        # 404 — branch on a specific subclass when you want to react to it.
+        dataset_items = []
     except ApifyApiError as err:
-        # The client raises ApifyApiError for API errors.
+        # Catch-all for every other API error.
         print(f'API error: {err}')
+        dataset_items = []
+
+    print(f'Fetched {len(dataset_items)} items.')
 
 
 if __name__ == '__main__':

docs/04_upgrading/upgrading_to_v3.mdx

@@ -46,6 +46,10 @@ status = run.status
 
 All model classes are generated from the Apify OpenAPI specification and live in `apify_client._models` module. They are configured with `extra='allow'`, so any new fields added to the API in the future are preserved on the model instance. Fields are accessed using their Python snake_case names:
 
+:::warning
+The `apify_client._models`, `apify_client._typeddicts`, and `apify_client._literals` modules are internal. The examples below import from them for convenience, but use them at your own risk — their contents are regenerated from the OpenAPI specification and the public API of these modules is not stable across minor versions of `apify-client`.
+:::
+
 ```python
 run.default_dataset_id   # ✓ use snake_case attribute names
 run.id
@@ -191,19 +195,7 @@ If your code relied on the previous global timeout behavior, review the timeout
 
 ## Exception subclasses for API errors
 
-<ApiLink to="class/ApifyApiError">`ApifyApiError`</ApiLink> now dispatches to a dedicated subclass based on the HTTP status code of the failed response. Instantiating `ApifyApiError` directly still works — it returns the most specific subclass for the status — so existing `except ApifyApiError` handlers are unaffected.
-
-The following subclasses are available:
-
-| Status | Subclass |
-|---|---|
-| 400 | <ApiLink to="class/InvalidRequestError">`InvalidRequestError`</ApiLink> |
-| 401 | <ApiLink to="class/UnauthorizedError">`UnauthorizedError`</ApiLink> |
-| 403 | <ApiLink to="class/ForbiddenError">`ForbiddenError`</ApiLink> |
-| 404 | <ApiLink to="class/NotFoundError">`NotFoundError`</ApiLink> |
-| 409 | <ApiLink to="class/ConflictError">`ConflictError`</ApiLink> |
-| 429 | <ApiLink to="class/RateLimitError">`RateLimitError`</ApiLink> |
-| 5xx | <ApiLink to="class/ServerError">`ServerError`</ApiLink> |
+The Apify client now provides dedicated error subclasses based on the HTTP status code of the failed response. Instantiating <ApiLink to="class/ApifyApiError">`ApifyApiError`</ApiLink> directly still works — it returns the most specific subclass for the status — so existing `except ApifyApiError` handlers are unaffected. See the [Error handling](/docs/concepts/error-handling#error-subclasses) concept page for the full status-to-subclass mapping.
 
 You can now branch on error kind without inspecting `status_code` or `type`: