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.

ScrapeDoJSONErrorMessage

Bases: BaseModel

Structured representation of a Scrape.do JSON error envelope.

API Response Errors

For APIResponseErrors, Scrape.do returns a JSON body containing information about what went wrong. This model unifies access to those responses and drives exception routing.

Not Official

• The schema was reconstructed from manual testing against the Scrape.do API

• New keys are silently ignored (extra="ignore") so server-side additions don't break parsing

• Missing keys fall back to their defaults.

is_auth_throttle property

Whether the envelope's messages match Scrape.do's authentication-throttle phrase.

Returns:

Type	Description
bool	True if any of messages contains the throttle substring, False otherwise.

try_from_response(raw_resp) classmethod

Parse a Scrape.do error envelope, or return None if the response doesn't look like one.

Parameters:

Name	Type	Description	Default
raw_resp	Response	The raw httpx.Response object.	required

Returns:

Type	Description
Optional[ScrapeDoJSONErrorMessage]	A ScrapeDoJSONErrorMessage when the response body parses as a JSON dict containing at least one Scrape.do error key and pydantic validation succeeds. None otherwise. Never raises.

__str__()

Generates a human-readable rendering for inclusion in exception messages.

Returns:

Type	Description
str	A multi-line string with all fields labeled.

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.

Parameters:

Name	Type	Description	Default
message	str	Error message to be displayed	required
request	Optional[PreparedScrapeDoRequest]	Object containing the request's information if it exists, otherwise None.	None
response	Optional[ScrapeDoResponse]	Object containing the response's information if it exists, otherwise None	None

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
message	str	The raw response body or error message from the target.	required
target_status_code	int	The HTTP status code returned by the target website.	required
raw_response	Response	The raw HTTP response object.	required
request	Optional[PreparedScrapeDoRequest]	Object containing the request's information if it exists, otherwise None.	None
response	Optional[ScrapeDoResponse]	Object containing the response's information if it exists, otherwise None	None

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.

Parameters:

Name	Type	Description	Default
raw_response	Response	The raw HTTP response object.	required
request	Optional[PreparedScrapeDoRequest]	Object containing the request's information if it exists, otherwise None.	None
response	Optional[ScrapeDoResponse]	Object containing the response's information if it exists, otherwise None	None

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
raw_response	Response	The raw HTTP response object.	required
request	Optional[PreparedScrapeDoRequest]	Object containing the request's information if it exists, otherwise None.	None
response	Optional[ScrapeDoResponse]	Object containing the response's information if it exists, otherwise None	None

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.

RotatedSessionError

Bases: ScrapeDoError

Raised when a user-defined session_validator determines that the target website's state has been lost (e.g., logged out, CAPTCHA triggered), indicating that Scrape.do silently rotated the proxy exit node.

Parameters:

Name	Type	Description	Default
message	str	Error message to be displayed	required
raw_response	Response	The raw HTTP response object.	required
request	PreparedScrapeDoRequest	Object containing the request's information	required
response	Optional[ScrapeDoResponse]	Object containing the response's information	required