0
# Exception Handling
1

2
Comprehensive exception classes for different error conditions in Manager API communication, authentication, action execution, and configuration management.
3

4
## Capabilities
5

6
### Base Exception Classes
7

8
#### BaseException
9

10
```python { .api }
11
class BaseException(Exception):
12
    """
13
    Base class for all py-Asterisk exceptions.
14
    
15
    Attributes:
16
        _prefix: Error message prefix for this exception type
17
        _error: Specific error message
18
    """
19
    
20
    def __init__(error: str):
21
        """Initialize with specific error message."""
22
    
23
    def __str__() -> str:
24
        """Return formatted error message: '{_prefix}: {_error}'"""
25
```
26

27
### Manager API Exceptions
28

29
#### Authentication Errors
30

31
```python { .api }
32
class AuthenticationFailure(BaseException):
33
    """
34
    Raised when authentication to the PBX instance fails.
35
    Usually indicates incorrect username/password or insufficient privileges.
36
    """
37
```
38

39
#### Communication Errors
40

41
```python { .api }
42
class CommunicationError(BaseException):
43
    """
44
    Raised when the PBX responds in an unexpected manner.
45
    Indicates protocol-level communication problems.
46
    """
47
    
48
    def __init__(packet: dict, msg: str = None):
49
        """
50
        Initialize with problematic packet and optional message.
51
        
52
        Args:
53
            packet: The Manager API packet that caused the error
54
            msg: Additional error description
55
        """
56
```
57

58
#### Connection Errors
59

60
```python { .api }
61
class GoneAwayError(BaseException):
62
    """
63
    Raised when the Manager connection becomes closed unexpectedly.
64
    Usually indicates network issues or Asterisk restart.
65
    """
66
```
67

68
#### Action Errors
69

70
```python { .api }
71
class ActionFailed(BaseException):
72
    """
73
    Raised when a PBX action fails.
74
    The Manager API returned an error response for the requested action.
75
    """
76

77
class PermissionDenied(BaseException):
78
    """
79
    Raised when connection is not permitted to perform requested action.
80
    User lacks necessary Manager API privileges.
81
    """
82
```
83

84
#### Internal Errors
85

86
```python { .api }
87
class InternalError(BaseException):
88
    """
89
    Raised when an error occurs within a Manager object.
90
    Indicates a problem in the py-Asterisk library itself.
91
    """
92
```
93

94
### Configuration Exceptions
95

96
```python { .api }
97
class ConfigurationError(BaseException):
98
    """
99
    Raised when there is a problem with configuration.
100
    Could be missing files, invalid format, or bad values.
101
    """
102
```
103

104
### Utility Exceptions
105

106
```python { .api }
107
class SubscriptionError(BaseException):
108
    """
109
    Raised when attempt to register the same (event, handler) tuple twice.
110
    Prevents duplicate event subscriptions.
111
    """
112

113
class ArgumentsError(BaseException):
114
    """
115
    Raised for bad command-line arguments in CLI functions.
116
    """
117
```
118

119
## Usage Examples
120

121
### Basic Exception Handling
122

123
```python
124
from Asterisk.Manager import Manager, AuthenticationFailure, CommunicationError
125

126
try:
127
    manager = Manager(('127.0.0.1', 5038), 'baduser', 'wrongpass')
128
except AuthenticationFailure as e:
129
    print(f"Login failed: {e}")
130
    # Handle authentication error - check credentials
131
except CommunicationError as e:
132
    print(f"Communication problem: {e}")
133
    # Handle protocol errors - check Asterisk configuration
134
```
135

136
### Comprehensive Error Handling
137

138
```python
139
from Asterisk.Manager import (
140
    Manager, AuthenticationFailure, CommunicationError, 
141
    GoneAwayError, ActionFailed, PermissionDenied
142
)
143

144
def robust_manager_operation():
145
    manager = None
146
    try:
147
        # Connect
148
        manager = Manager(('127.0.0.1', 5038), 'admin', 'secret')
149
        
150
        # Execute action
151
        result = manager.ShowChannels()
152
        return result
153
        
154
    except AuthenticationFailure:
155
        print("Authentication failed - check username/password")
156
        return None
157
        
158
    except PermissionDenied:
159
        print("Permission denied - user needs 'call' privilege")
160
        return None
161
        
162
    except ActionFailed as e:
163
        print(f"Action failed: {e}")
164
        return None
165
        
166
    except CommunicationError as e:
167
        print(f"Communication error: {e}")
168
        # Could retry with exponential backoff
169
        return None
170
        
171
    except GoneAwayError:
172
        print("Connection lost - Asterisk may have restarted")
173
        # Could attempt reconnection
174
        return None
175
        
176
    finally:
177
        if manager:
178
            try:
179
                manager.Logoff()
180
            except:
181
                pass  # Connection may already be dead
182
```
183

184
### Channel Operation Error Handling
185

186
```python
187
from Asterisk.Manager import Manager, ActionFailed
188

189
manager = Manager(('127.0.0.1', 5038), 'admin', 'secret')
190

191
try:
192
    # Try to hang up a channel
193
    channel = manager.get_channel('SIP/1001-00000001')
194
    channel.Hangup()
195
    
196
except ActionFailed as e:
197
    if 'No such channel' in str(e):
198
        print("Channel already hung up or doesn't exist")
199
    else:
200
        print(f"Hangup failed: {e}")
201
```
202

203
### Configuration Error Handling
204

205
```python
206
from Asterisk.Config import Config, ConfigurationError
207

208
try:
209
    config = Config('/etc/asterisk/py-asterisk.conf')
210
except ConfigurationError as e:
211
    print(f"Configuration error: {e}")
212
    # Fall back to default configuration or prompt user
213
    config = None
214
```
215

216
### Event Subscription Error Handling
217

218
```python
219
from Asterisk.Util import EventCollection, SubscriptionError
220

221
events = EventCollection()
222

223
def my_handler(event):
224
    print(f"Got event: {event}")
225

226
try:
227
    events.subscribe('Hangup', my_handler)
228
    events.subscribe('Hangup', my_handler)  # Duplicate!
229
except SubscriptionError as e:
230
    print(f"Subscription error: {e}")
231
    # Handler already subscribed
232
```
233

234
### CLI Error Handling
235

236
```python
237
from Asterisk.CLI import command_line, ArgumentsError
238

239
try:
240
    command_line(['py-asterisk', 'action'])  # Missing action name
241
except ArgumentsError as e:
242
    print(f"Invalid arguments: {e}")
243
    # Show usage information
244
```
245

246
## Error Categories
247

248
### Network/Connection Errors
249
- `CommunicationError`: Protocol-level problems
250
- `GoneAwayError`: Connection lost
251
- `AuthenticationFailure`: Login failed
252

253
### Permission/Access Errors  
254
- `PermissionDenied`: Insufficient Manager API privileges
255
- `ActionFailed`: Action not allowed or failed
256

257
### Configuration Errors
258
- `ConfigurationError`: Config file problems
259

260
### Usage Errors
261
- `ArgumentsError`: Bad CLI arguments  
262
- `SubscriptionError`: Duplicate event subscriptions
263

264
### Internal Errors
265
- `InternalError`: Library bugs or unexpected states