Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions docs/02_concepts/04_error_handling.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -43,4 +43,8 @@ All subclasses inherit from <ApiLink to="class/ApifyApiError">`ApifyApiError`</A
</TabItem>
</Tabs>

## Response validation errors

The client validates every API response against its model. When a response does not match, for example because the API changed ahead of the client, it raises a <ApiLink to="class/ResponseValidationError">`ResponseValidationError`</ApiLink> instead of a bare `pydantic.ValidationError`. It inherits from <ApiLink to="class/ApifyClientError">`ApifyClientError`</ApiLink>, so a handler for client errors catches it. It also inherits from `pydantic.ValidationError`, so `errors()` lists the individual mismatches and an existing `except pydantic.ValidationError` or `except ValueError` handler keeps working. The `method` and `url` attributes name the request whose response failed, and `__cause__` holds the original validation error.

For a complete list of error classes, see the <ApiLink to="class/ApifyApiError">`ApifyApiError`</ApiLink> reference.
18 changes: 9 additions & 9 deletions src/apify_client/_resource_clients/actor.py
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,7 @@
)
from apify_client._resource_clients._resource_client import ResourceClient, ResourceClientAsync
from apify_client._utils.encoding import encode_key_value_store_record_value, encode_webhooks_to_base64
from apify_client._utils.http import response_to_dict
from apify_client._utils.http import response_to_dict, validate_response
from apify_client._utils.server_args import build_actor_standby
from apify_client._utils.time import to_seconds
from apify_client._utils.wait_for_resources import (
Expand Down Expand Up @@ -104,7 +104,7 @@ def get(self, *, timeout: Timeout = 'short') -> ActorResource | None:
result = self._get(timeout=timeout)
if result is None:
return None
return ActorResponse.model_validate(result).data
return validate_response(ActorResponse, result).data

def update(
self,
Expand Down Expand Up @@ -264,7 +264,7 @@ def update(
tagged_builds=tagged_builds,
)
result = self._update(timeout=timeout, **actor_fields.model_dump(by_alias=True, exclude_none=True))
return ActorResponse.model_validate(result).data
return validate_response(ActorResponse, result).data

def delete(self, *, timeout: Timeout = 'short') -> None:
"""Delete the Actor.
Expand Down Expand Up @@ -368,7 +368,7 @@ def start(
)

result = response_to_dict(response)
return RunResponse.model_validate(result).data
return validate_response(RunResponse, result).data

def call(
self,
Expand Down Expand Up @@ -522,7 +522,7 @@ def build(
)

result = response_to_dict(response)
return BuildResponse.model_validate(result).data
return validate_response(BuildResponse, result).data

def builds(self) -> BuildCollectionClient:
"""Retrieve a client for the builds of this Actor."""
Expand Down Expand Up @@ -751,7 +751,7 @@ async def get(self, *, timeout: Timeout = 'short') -> ActorResource | None:
result = await self._get(timeout=timeout)
if result is None:
return None
return ActorResponse.model_validate(result).data
return validate_response(ActorResponse, result).data

async def update(
self,
Expand Down Expand Up @@ -911,7 +911,7 @@ async def update(
tagged_builds=tagged_builds,
)
result = await self._update(timeout=timeout, **actor_fields.model_dump(by_alias=True, exclude_none=True))
return ActorResponse.model_validate(result).data
return validate_response(ActorResponse, result).data

async def delete(self, *, timeout: Timeout = 'short') -> None:
"""Delete the Actor.
Expand Down Expand Up @@ -1015,7 +1015,7 @@ async def start(
)

result = response_to_dict(response)
return RunResponse.model_validate(result).data
return validate_response(RunResponse, result).data

async def call(
self,
Expand Down Expand Up @@ -1170,7 +1170,7 @@ async def build(
)

result = response_to_dict(response)
return BuildResponse.model_validate(result).data
return validate_response(BuildResponse, result).data

def builds(self) -> BuildCollectionClientAsync:
"""Retrieve a client for the builds of this Actor."""
Expand Down
9 changes: 5 additions & 4 deletions src/apify_client/_resource_clients/actor_collection.py
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,7 @@
)
from apify_client._pagination import get_items_iterator, get_items_iterator_async
from apify_client._resource_clients._resource_client import ResourceClient, ResourceClientAsync
from apify_client._utils.http import validate_response
from apify_client._utils.server_args import build_actor_standby
from apify_client._utils.time import to_seconds

Expand Down Expand Up @@ -71,7 +72,7 @@ def list(
The list of available Actors matching the specified filters.
"""
result = self._list(timeout=timeout, my=my, limit=limit, offset=offset, desc=desc, sortBy=sort_by)
return ListOfActorsResponse.model_validate(result).data
return validate_response(ListOfActorsResponse, result).data

def iterate(
self,
Expand Down Expand Up @@ -259,7 +260,7 @@ def create(
),
)
result = self._create(timeout=timeout, **actor_fields.model_dump(by_alias=True, exclude_none=True))
return ActorResponse.model_validate(result).data
return validate_response(ActorResponse, result).data


@docs_group('Resource clients')
Expand Down Expand Up @@ -307,7 +308,7 @@ async def list(
The list of available Actors matching the specified filters.
"""
result = await self._list(timeout=timeout, my=my, limit=limit, offset=offset, desc=desc, sortBy=sort_by)
return ListOfActorsResponse.model_validate(result).data
return validate_response(ListOfActorsResponse, result).data

def iterate(
self,
Expand Down Expand Up @@ -495,4 +496,4 @@ async def create(
),
)
result = await self._create(timeout=timeout, **actor_fields.model_dump(by_alias=True, exclude_none=True))
return ActorResponse.model_validate(result).data
return validate_response(ActorResponse, result).data
9 changes: 5 additions & 4 deletions src/apify_client/_resource_clients/actor_env_var.py
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,7 @@
from apify_client._docs import docs_group
from apify_client._models import EnvVar, EnvVarResponse
from apify_client._resource_clients._resource_client import ResourceClient, ResourceClientAsync
from apify_client._utils.http import validate_response

if TYPE_CHECKING:
from apify_client.types import Timeout
Expand Down Expand Up @@ -45,7 +46,7 @@ def get(self, *, timeout: Timeout = 'short') -> EnvVar | None:
result = self._get(timeout=timeout)
if result is None:
return None
return EnvVarResponse.model_validate(result).data
return validate_response(EnvVarResponse, result).data

def update(
self,
Expand All @@ -72,7 +73,7 @@ def update(
timeout=timeout,
**EnvVar(name=name, value=value, is_secret=is_secret).model_dump(by_alias=True, exclude_none=True),
)
return EnvVarResponse.model_validate(result).data
return validate_response(EnvVarResponse, result).data

def delete(self, *, timeout: Timeout = 'short') -> None:
"""Delete the Actor environment variable.
Expand Down Expand Up @@ -120,7 +121,7 @@ async def get(self, *, timeout: Timeout = 'short') -> EnvVar | None:
result = await self._get(timeout=timeout)
if result is None:
return None
return EnvVarResponse.model_validate(result).data
return validate_response(EnvVarResponse, result).data

async def update(
self,
Expand All @@ -147,7 +148,7 @@ async def update(
timeout=timeout,
**EnvVar(name=name, value=value, is_secret=is_secret).model_dump(by_alias=True, exclude_none=True),
)
return EnvVarResponse.model_validate(result).data
return validate_response(EnvVarResponse, result).data

async def delete(self, *, timeout: Timeout = 'short') -> None:
"""Delete the Actor environment variable.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,7 @@
from apify_client._docs import docs_group
from apify_client._models import EnvVar, EnvVarResponse, ListOfEnvVars, ListOfEnvVarsResponse
from apify_client._resource_clients._resource_client import ResourceClient, ResourceClientAsync
from apify_client._utils.http import validate_response

if TYPE_CHECKING:
from collections.abc import AsyncIterator, Iterator
Expand Down Expand Up @@ -43,7 +44,7 @@ def list(self, *, timeout: Timeout = 'short') -> ListOfEnvVars:
The list of available Actor environment variables.
"""
result = self._list(timeout=timeout)
return ListOfEnvVarsResponse.model_validate(result).data
return validate_response(ListOfEnvVarsResponse, result).data

def iterate(self, *, timeout: Timeout = 'short') -> Iterator[EnvVar]:
"""Iterate over the available Actor environment variables.
Expand Down Expand Up @@ -88,7 +89,7 @@ def create(
timeout=timeout,
**EnvVar(name=name, value=value, is_secret=is_secret).model_dump(by_alias=True, exclude_none=True),
)
return EnvVarResponse.model_validate(result).data
return validate_response(EnvVarResponse, result).data


@docs_group('Resource clients')
Expand Down Expand Up @@ -122,7 +123,7 @@ async def list(self, *, timeout: Timeout = 'short') -> ListOfEnvVars:
The list of available Actor environment variables.
"""
result = await self._list(timeout=timeout)
return ListOfEnvVarsResponse.model_validate(result).data
return validate_response(ListOfEnvVarsResponse, result).data

async def iterate(self, *, timeout: Timeout = 'short') -> AsyncIterator[EnvVar]:
"""Iterate over the available Actor environment variables.
Expand Down Expand Up @@ -168,4 +169,4 @@ async def create(
timeout=timeout,
**EnvVar(name=name, value=value, is_secret=is_secret).model_dump(by_alias=True, exclude_none=True),
)
return EnvVarResponse.model_validate(result).data
return validate_response(EnvVarResponse, result).data
6 changes: 3 additions & 3 deletions src/apify_client/_resource_clients/actor_server.py
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@
from apify_client._docs import docs_group
from apify_client._models import ActorResponse
from apify_client._resource_clients._resource_client import ResourceClient, ResourceClientAsync
from apify_client._utils.http import merge_headers, response_to_dict
from apify_client._utils.http import merge_headers, response_to_dict, validate_response
from apify_client.errors import ApifyClientError
from apify_client.http_compressors._resolve import resolve_compressor

Expand Down Expand Up @@ -239,7 +239,7 @@ def _get_server_actor(self, *, timeout: Timeout) -> tuple[ActorResource, str]:
The Actor and the URL of its server.
"""
response = self._http_client.call(url=self._build_url(), method='GET', timeout=timeout)
actor = ActorResponse.model_validate(response_to_dict(response)).data
actor = validate_response(ActorResponse, response_to_dict(response)).data
url = actor.standby_url
if url is None:
raise ApifyClientError(f'Actor {self.resource_id} is not a Server Actor.')
Expand Down Expand Up @@ -442,7 +442,7 @@ async def _get_server_actor(self, *, timeout: Timeout) -> tuple[ActorResource, s
The Actor and the URL of its server.
"""
response = await self._http_client.call(url=self._build_url(), method='GET', timeout=timeout)
actor = ActorResponse.model_validate(response_to_dict(response)).data
actor = validate_response(ActorResponse, response_to_dict(response)).data
url = actor.standby_url
if url is None:
raise ApifyClientError(f'Actor {self.resource_id} is not a Server Actor.')
Expand Down
9 changes: 5 additions & 4 deletions src/apify_client/_resource_clients/actor_version.py
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,7 @@
VersionResponse,
)
from apify_client._resource_clients._resource_client import ResourceClient, ResourceClientAsync
from apify_client._utils.http import validate_response

if TYPE_CHECKING:
from apify_client._literals import VersionSourceType
Expand Down Expand Up @@ -63,7 +64,7 @@ def get(self, *, timeout: Timeout = 'short') -> Version | None:
result = self._get(timeout=timeout)
if result is None:
return None
return VersionResponse.model_validate(result).data
return validate_response(VersionResponse, result).data

def update(
self,
Expand Down Expand Up @@ -121,7 +122,7 @@ def update(
actor_path=actor_path,
)
result = self._update(timeout=timeout, **version_fields.model_dump(by_alias=True, exclude_none=True))
return VersionResponse.model_validate(result).data
return validate_response(VersionResponse, result).data

def delete(self, *, timeout: Timeout = 'short') -> None:
"""Delete the Actor version.
Expand Down Expand Up @@ -187,7 +188,7 @@ async def get(self, *, timeout: Timeout = 'short') -> Version | None:
result = await self._get(timeout=timeout)
if result is None:
return None
return VersionResponse.model_validate(result).data
return validate_response(VersionResponse, result).data

async def update(
self,
Expand Down Expand Up @@ -245,7 +246,7 @@ async def update(
actor_path=actor_path,
)
result = await self._update(timeout=timeout, **version_fields.model_dump(by_alias=True, exclude_none=True))
return VersionResponse.model_validate(result).data
return validate_response(VersionResponse, result).data

async def delete(self, *, timeout: Timeout = 'short') -> None:
"""Delete the Actor version.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,7 @@
VersionResponse,
)
from apify_client._resource_clients._resource_client import ResourceClient, ResourceClientAsync
from apify_client._utils.http import validate_response

if TYPE_CHECKING:
from collections.abc import AsyncIterator, Iterator
Expand Down Expand Up @@ -58,7 +59,7 @@ def list(self, *, timeout: Timeout = 'short') -> ListOfVersions:
The list of available Actor versions.
"""
result = self._list(timeout=timeout)
return ListOfVersionsResponse.model_validate(result).data
return validate_response(ListOfVersionsResponse, result).data

def iterate(self, *, timeout: Timeout = 'short') -> Iterator[Version]:
"""Iterate over the available Actor versions.
Expand Down Expand Up @@ -135,7 +136,7 @@ def create(
actor_path=actor_path,
)
result = self._create(timeout=timeout, **version_fields.model_dump(by_alias=True, exclude_none=True))
return VersionResponse.model_validate(result).data
return validate_response(VersionResponse, result).data


@docs_group('Resource clients')
Expand Down Expand Up @@ -169,7 +170,7 @@ async def list(self, *, timeout: Timeout = 'short') -> ListOfVersions:
The list of available Actor versions.
"""
result = await self._list(timeout=timeout)
return ListOfVersionsResponse.model_validate(result).data
return validate_response(ListOfVersionsResponse, result).data

async def iterate(self, *, timeout: Timeout = 'short') -> AsyncIterator[Version]:
"""Iterate over the available Actor versions.
Expand Down Expand Up @@ -247,4 +248,4 @@ async def create(
actor_path=actor_path,
)
result = await self._create(timeout=timeout, **version_fields.model_dump(by_alias=True, exclude_none=True))
return VersionResponse.model_validate(result).data
return validate_response(VersionResponse, result).data
14 changes: 7 additions & 7 deletions src/apify_client/_resource_clients/build.py
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@
from apify_client._docs import docs_group
from apify_client._models import Build, BuildResponse
from apify_client._resource_clients._resource_client import ResourceClient, ResourceClientAsync
from apify_client._utils.http import response_to_dict
from apify_client._utils.http import response_to_dict, validate_response

if TYPE_CHECKING:
from datetime import timedelta
Expand Down Expand Up @@ -53,7 +53,7 @@ def get(self, *, wait_for_finish: timedelta | int | None = None, timeout: Timeou
result = self._get(timeout=request_timeout, waitForFinish=wait_for_finish_secs)
if result is None:
return None
return BuildResponse.model_validate(result).data
return validate_response(BuildResponse, result).data

def delete(self, *, timeout: Timeout = 'short') -> None:
"""Delete the build.
Expand Down Expand Up @@ -83,7 +83,7 @@ def abort(self, *, timeout: Timeout = 'short') -> Build:
timeout=timeout,
)
result = response_to_dict(response)
return BuildResponse.model_validate(result).data
return validate_response(BuildResponse, result).data

def get_open_api_definition(self, *, timeout: Timeout = 'medium') -> dict:
"""Return OpenAPI definition of the Actor's build.
Expand Down Expand Up @@ -122,7 +122,7 @@ def wait_for_finish(
wait_duration=wait_duration,
timeout=timeout,
)
return Build.model_validate(result) if result is not None else None
return validate_response(Build, result) if result is not None else None

def log(self) -> LogClient:
"""Get the client for the log of the Actor build.
Expand Down Expand Up @@ -177,7 +177,7 @@ async def get(self, *, wait_for_finish: timedelta | int | None = None, timeout:
result = await self._get(timeout=request_timeout, waitForFinish=wait_for_finish_secs)
if result is None:
return None
return BuildResponse.model_validate(result).data
return validate_response(BuildResponse, result).data

async def abort(self, *, timeout: Timeout = 'short') -> Build:
"""Abort the Actor build which is starting or currently running and return its details.
Expand All @@ -197,7 +197,7 @@ async def abort(self, *, timeout: Timeout = 'short') -> Build:
timeout=timeout,
)
result = response_to_dict(response)
return BuildResponse.model_validate(result).data
return validate_response(BuildResponse, result).data

async def delete(self, *, timeout: Timeout = 'short') -> None:
"""Delete the build.
Expand Down Expand Up @@ -246,7 +246,7 @@ async def wait_for_finish(
wait_duration=wait_duration,
timeout=timeout,
)
return Build.model_validate(result) if result is not None else None
return validate_response(Build, result) if result is not None else None

def log(self) -> LogClientAsync:
"""Get the client for the log of the Actor build.
Expand Down
Loading
Loading