0
# Error Handling
1

2
Comprehensive exception hierarchy for handling proxy connection failures, timeouts, and authentication errors. All proxy-related exceptions are imported from the python-socks library.
3

4
## Capabilities
5

6
### Exception Hierarchy
7

8
The library provides a structured exception hierarchy for different types of proxy errors.
9

10
```python { .api }
11
class ProxyError(Exception):
12
    """
13
    Base exception for all proxy-related errors.
14
    
15
    This is the parent class for all proxy exceptions and can be used
16
    to catch any proxy-related error.
17
    """
18

19
class ProxyConnectionError(ProxyError):
20
    """
21
    Exception raised when proxy connection fails.
22
    
23
    Raised when the connection to the proxy server cannot be established,
24
    including network errors, refused connections, and proxy server errors.
25
    """
26

27
class ProxyTimeoutError(ProxyError):
28
    """
29
    Exception raised when proxy operations timeout.
30
    
31
    Raised when connection attempts or data transfer through the proxy
32
    exceeds the specified timeout duration.
33
    """
34
```
35

36
### Error Handling Patterns
37

38
#### Basic Error Handling
39

40
```python
41
import aiohttp
42
from aiohttp_socks import ProxyConnector, ProxyError, ProxyConnectionError, ProxyTimeoutError
43

44
async def fetch_with_error_handling(url):
45
    connector = ProxyConnector.from_url('socks5://127.0.0.1:1080')
46
    
47
    try:
48
        async with aiohttp.ClientSession(connector=connector) as session:
49
            async with session.get(url, timeout=10) as response:
50
                return await response.text()
51
                
52
    except ProxyConnectionError as e:
53
        print(f"Failed to connect to proxy: {e}")
54
        return None
55
        
56
    except ProxyTimeoutError as e:
57
        print(f"Proxy operation timed out: {e}")
58
        return None
59
        
60
    except ProxyError as e:
61
        print(f"General proxy error: {e}")
62
        return None
63
```
64

65
#### Fallback Proxy Strategy
66

67
```python
68
from aiohttp_socks import ChainProxyConnector, ProxyConnector, ProxyError
69

70
async def fetch_with_fallback(url, proxy_urls):
71
    """Try multiple proxies until one works."""
72
    
73
    for proxy_url in proxy_urls:
74
        try:
75
            connector = ProxyConnector.from_url(proxy_url)
76
            async with aiohttp.ClientSession(connector=connector) as session:
77
                async with session.get(url, timeout=10) as response:
78
                    return await response.text()
79
                    
80
        except ProxyError as e:
81
            print(f"Proxy {proxy_url} failed: {e}")
82
            continue
83
            
84
    raise Exception("All proxies failed")
85
```
86

87
#### Chain Error Handling
88

89
```python
90
from aiohttp_socks import ChainProxyConnector, ProxyError
91

92
async def fetch_with_chain_fallback(url):
93
    """Try different proxy chain configurations."""
94
    
95
    proxy_chains = [
96
        ['socks5://proxy1.example.com:1080', 'socks4://proxy2.example.com:1081'],
97
        ['http://proxy3.example.com:3128'],
98
        ['socks5://backup-proxy.example.com:1080']
99
    ]
100
    
101
    for chain_urls in proxy_chains:
102
        try:
103
            connector = ChainProxyConnector.from_urls(chain_urls)
104
            async with aiohttp.ClientSession(connector=connector) as session:
105
                async with session.get(url, timeout=15) as response:
106
                    return await response.text()
107
                    
108
        except ProxyError as e:
109
            print(f"Proxy chain {chain_urls} failed: {e}")
110
            continue
111
            
112
    raise Exception("All proxy chains failed")
113
```
114

115
### Common Error Scenarios
116

117
#### Connection Failures
118
- **ProxyConnectionError**: Raised when the proxy server is unreachable, refuses connections, or returns connection errors
119
- Network connectivity issues between client and proxy
120
- Proxy server is down or overloaded
121
- Incorrect proxy host or port configuration
122

123
#### Authentication Failures  
124
- **ProxyConnectionError**: Raised when proxy authentication fails
125
- Invalid username or password credentials
126
- Proxy requires authentication but none provided
127
- Authentication method not supported by proxy
128

129
#### Timeout Scenarios
130
- **ProxyTimeoutError**: Raised when operations exceed timeout limits
131
- Slow proxy server response times
132
- Network latency issues
133
- Large data transfers through slow proxies
134

135
#### Protocol Errors
136
- **ProxyError**: General proxy protocol errors
137
- Unsupported proxy type or protocol version
138
- Malformed proxy responses
139
- Protocol negotiation failures
140

141
### Integration with aiohttp Errors
142

143
Proxy errors work alongside aiohttp's built-in exception handling:
144

145
```python
146
import aiohttp
147
from aiohttp_socks import ProxyConnector, ProxyError
148

149
async def comprehensive_error_handling(url):
150
    connector = ProxyConnector.from_url('socks5://127.0.0.1:1080')
151
    
152
    try:
153
        async with aiohttp.ClientSession(connector=connector) as session:
154
            async with session.get(url) as response:
155
                return await response.text()
156
                
157
    except ProxyError as e:
158
        print(f"Proxy error: {e}")
159
        
160
    except aiohttp.ClientConnectorError as e:
161
        print(f"Connection error: {e}")
162
        
163
    except aiohttp.ClientTimeout as e:
164
        print(f"Request timeout: {e}")
165
        
166
    except aiohttp.ClientError as e:
167
        print(f"Client error: {e}")
168
        
169
    return None
170
```