proxywhirl.exceptions¶

Custom exceptions for ProxyWhirl.

All exceptions support additional metadata for debugging and retry logic.

Exceptions¶

`CacheCorruptionError`	Raised when cache data is corrupted and cannot be recovered.
`CacheStorageError`	Raised when cache storage backend is unavailable.
`CacheValidationError`	Raised when cache entry fails validation.
`ProxyAuthenticationError`	Raised when proxy authentication fails.
`ProxyConnectionError`	Raised when unable to connect through a proxy.
`ProxyFetchError`	Raised when fetching proxies from external sources fails.
`ProxyPoolEmptyError`	Raised when attempting to select from an empty proxy pool.
`ProxyStorageError`	Raised when proxy storage operations fail.
`ProxyValidationError`	Raised when proxy URL or configuration is invalid.
`ProxyWhirlError`	Base exception for all ProxyWhirl errors.
`RequestQueueFullError`	Raised when the request queue is full and cannot accept more requests.

Classes¶

ProxyErrorCode

Error codes for programmatic error handling.

Functions¶

redact_url(url)

Redact sensitive information from a URL.

Module Contents¶

exception proxywhirl.exceptions.CacheCorruptionError(message='Cache data is corrupted', **kwargs)[source]¶

Bases: ProxyWhirlError

Raised when cache data is corrupted and cannot be recovered.

Actionable guidance: - Clear the cache and reinitialize - Check for disk errors or corruption - Verify cache format version compatibility

Initialize with cache corruption-specific defaults.

Parameters:

message (str)
kwargs (Any)

exception proxywhirl.exceptions.CacheStorageError(message='Cache storage backend unavailable', **kwargs)[source]¶

Bases: ProxyWhirlError

Raised when cache storage backend is unavailable.

Actionable guidance: - Verify cache backend (Redis, Memcached) is running - Check network connectivity to cache server - Ensure cache credentials are valid - Review cache server logs for errors

Initialize with cache storage-specific defaults.

Parameters:

message (str)
kwargs (Any)

exception proxywhirl.exceptions.CacheValidationError(message, **kwargs)[source]¶

Bases: ValueError, ProxyWhirlError

Raised when cache entry fails validation.

Actionable guidance: - Check cache entry format - Verify data types match schema - Ensure required fields are present

Initialize with cache validation-specific defaults.

Parameters:

message (str)
kwargs (Any)

exception proxywhirl.exceptions.ProxyAuthenticationError(message='Proxy authentication failed', **kwargs)[source]¶

Bases: ProxyWhirlError

Raised when proxy authentication fails.

Actionable guidance: - Verify username and password are correct - Check if proxy requires specific auth method - Ensure credentials are not expired - Contact proxy provider if credentials should be valid

Initialize with auth-specific defaults.

Parameters:

message (str)
kwargs (Any)

exception proxywhirl.exceptions.ProxyConnectionError(message, **kwargs)[source]¶

Bases: ProxyWhirlError

Raised when unable to connect through a proxy.

Actionable guidance: - Verify proxy is reachable and not blocked - Check network connectivity - Ensure proxy supports the target protocol - Try increasing timeout value

Initialize with connection-specific defaults.

Parameters:

message (str)
kwargs (Any)

exception proxywhirl.exceptions.ProxyFetchError(message, **kwargs)[source]¶

Bases: ProxyWhirlError

Raised when fetching proxies from external sources fails.

Actionable guidance: - Verify the source URL is accessible - Check API credentials if required - Ensure the response format matches expectations - Review rate limits with the provider

Initialize with fetch-specific defaults.

Parameters:

message (str)
kwargs (Any)

exception proxywhirl.exceptions.ProxyPoolEmptyError(message='No proxies available in the pool', **kwargs)[source]¶

Bases: ProxyWhirlError

Raised when attempting to select from an empty proxy pool.

Actionable guidance: - Add proxies to the pool using add_proxy() or auto-fetch - Check if proxies were filtered out by health checks - Verify proxy sources are reachable

Initialize with pool-empty-specific defaults.

Parameters:

message (str)
kwargs (Any)

exception proxywhirl.exceptions.ProxyStorageError(message, **kwargs)[source]¶

Bases: ProxyWhirlError

Raised when proxy storage operations fail.

Actionable guidance: - Check file system permissions - Verify disk space is available - Ensure storage path is writable - Check database connection if using external storage

Initialize with storage-specific defaults.

Parameters:

message (str)
kwargs (Any)

exception proxywhirl.exceptions.ProxyValidationError(message, **kwargs)[source]¶

Bases: ProxyWhirlError

Raised when proxy URL or configuration is invalid.

Actionable guidance: - Verify the proxy URL format (e.g., http://host:port) - Check that the protocol is supported (http, https, socks5) - Ensure credentials are properly encoded

Initialize with validation-specific defaults.

Parameters:

message (str)
kwargs (Any)

exception proxywhirl.exceptions.ProxyWhirlError(message, *, proxy_url=None, error_type=None, error_code=None, retry_recommended=False, attempt_count=None, **metadata)[source]¶

Bases: Exception

Base exception for all ProxyWhirl errors.

Initialize exception with optional metadata.

Parameters:

message (str) – Human-readable error message
proxy_url (str | None) – URL of the proxy that caused the error (will be redacted)
error_type (str | None) – Type of error (e.g., “timeout”, “invalid_credentials”)
error_code (ProxyErrorCode | None) – Programmatic error code for handling
retry_recommended (bool) – Whether retrying the operation is recommended
attempt_count (int | None) – Number of attempts made before this error
**metadata (Any) – Additional error-specific metadata

to_dict()[source]¶

Convert exception to dictionary for logging/serialization.

Returns:: Dictionary representation of the error
Return type:: dict[str, Any]

exception proxywhirl.exceptions.RequestQueueFullError(message='Request queue is full', queue_size=None, **kwargs)[source]¶

Bases: ProxyWhirlError

Raised when the request queue is full and cannot accept more requests.

Actionable guidance: - Wait for pending requests to complete - Increase queue_size in configuration - Reduce request rate to avoid overloading the queue - Consider implementing request batching or throttling

Initialize with queue-specific defaults.

Parameters:

message (str)
queue_size (int | None)
kwargs (Any)

class proxywhirl.exceptions.ProxyErrorCode[source]¶

Bases: str, enum.Enum

Error codes for programmatic error handling.

Initialize self. See help(type(self)) for accurate signature.

proxywhirl.exceptions.redact_url(url)[source]¶

Redact sensitive information from a URL.

Removes username and password while preserving scheme, host, port, and path.

Parameters:: url (str) – URL to redact
Returns:: Redacted URL string
Return type:: str