Exceptions

exceptions

Custom exception hierarchy and network error routing for the Scrape.do SDK.

Dynamically parses API failures, distinguishes proxy infrastructure errors from target website blocks, and exposes programmatic flags for retry strategies.

ScrapeDoError

Bases: Exception

The base exception for all errors raised by the SDK.

Catching this exception guarantees that any error originating strictly from the SDK or the proxy network is handled.

APIConnectionError

Bases: ScrapeDoError

Raised when the SDK fails to connect to the Scrape.do gateway entirely.

This indicates a network-level failure such as DNS resolution issues, local internet outages, or hard socket timeouts.

TargetError

Bases: ScrapeDoError

Raised when the Scrape.do proxy connects, but the target website fails.

This exception is triggered when transparent_response=True is used, explicitly flagging that the destination URL returned a non-2xx status code.

Parameters:

Name	Type	Description	Default
target_status_code	int	The HTTP status code returned by the target website.	required
message	str	The raw response body or error message from the target.	required

is_waf_block property

Programmatic flag to identify if the target website blocked the proxy.

Returns:

Type	Description
bool	True if status code is either 401 or 403, False otherwise

is_throttled property

Programmatic flag to identify target-level rate limiting.

Returns:

Type	Description
bool	True if status code is 429, False otherwise

AuthenticationThrottleError

Bases: ScrapeDoError

Raised when high-frequency invalid requests trigger an authentication ban.

APIResponseError

Bases: ScrapeDoError

Dynamically parses and represents a Scrape.do API infrastructure error.

This acts as the base exception for all non-2xx HTTP responses returned by the Scrape.do gateway. It parses the JSON payloads to extract human-readable error messages.

Parameters:

Name	Type	Description	Default
response	Response	The raw HTTP response object.	required

AuthenticationError

Bases: APIResponseError

Raised when the API returns an HTTP 401 (Unauthorized).

Indicates that the provided API token is missing or invalid.

BadRequestError

Bases: APIResponseError

Raised when the API returns an HTTP 400 (Bad Request).

Indicates that the Scrape.do servers rejected the request configuration.

RateLimitError

Bases: APIResponseError

Raised when the API returns an HTTP 429 (Too Many Requests).

Indicates that the account has exceeded its concurrent request limit.

ServerError

Bases: APIResponseError

Raised when the API returns an HTTP 500+ status code.

Indicates a gateway failure or proxy pool outage.