0
# Exception Handling
1

2
ARM-specific error formatting and exception handling that extends Azure Core's OData v4 error format with additional ARM-specific error information. These classes provide enhanced error details for ARM operations.
3

4
## Capabilities
5

6
### TypedErrorInfo
7

8
Container for additional error information as defined in the ARM specification. Provides structured access to error type and detailed information.
9

10
```python { .api }
11
class TypedErrorInfo:
12
    """Additional info class defined in ARM specification.
13

14
    https://github.com/Azure/azure-resource-manager-rpc/blob/master/v1.0/common-api-details.md#error-response-content
15
    """
16
    
17
    def __init__(self, type: str, info: Mapping[str, Any]) -> None: ...
18
    def __str__(self) -> str: ...
19
```
20

21
#### Properties
22

23
- **type** (str): The type of additional error information
24
- **info** (Mapping[str, Any]): Detailed error information as key-value pairs
25

26
#### Usage Example
27

28
```python
29
from azure.mgmt.core.exceptions import TypedErrorInfo
30

31
# Create typed error info
32
error_info = TypedErrorInfo(
33
    type="PolicyViolation",
34
    info={
35
        "policyDefinitionId": "/subscriptions/.../policyDefinitions/allowed-locations",
36
        "policyAssignmentId": "/subscriptions/.../policyAssignments/location-policy",  
37
        "policyEffect": "deny"
38
    }
39
)
40

41
print(str(error_info))
42
# Output:
43
# Type: PolicyViolation
44
# Info: {
45
#     "policyDefinitionId": "/subscriptions/.../policyDefinitions/allowed-locations",
46
#     "policyAssignmentId": "/subscriptions/.../policyAssignments/location-policy",
47
#     "policyEffect": "deny"
48
# }
49
```
50

51
### ARMErrorFormat
52

53
Enhanced error format for ARM operations that extends OData v4 error format with ARM-specific additional information. Provides comprehensive error details including policy violations, resource constraints, and other ARM-specific error contexts.
54

55
```python { .api }
56
class ARMErrorFormat(ODataV4Format):
57
    """Describe error format from ARM, used at the base or inside "details" node.
58

59
    This format is compatible with ODataV4 format.
60
    https://github.com/Azure/azure-resource-manager-rpc/blob/master/v1.0/common-api-details.md#error-response-content
61
    """
62
    
63
    def __init__(self, json_object: Mapping[str, Any]) -> None: ...
64
    def __str__(self) -> str: ...
65
```
66

67
#### Properties
68

69
- **additional_info** (Sequence[TypedErrorInfo]): List of additional error information objects
70
- Inherits all OData v4 format properties: code, message, target, details, innererror
71

72
#### Error Response Structure
73

74
ARM error responses follow this structure:
75
```json
76
{
77
  "error": {
78
    "code": "InvalidParameter",
79
    "message": "The parameter 'location' is invalid.",
80
    "target": "location",
81
    "details": [...],
82
    "innererror": {...},
83
    "additionalInfo": [
84
      {
85
        "type": "PolicyViolation",
86
        "info": {
87
          "policyDefinitionId": "...",
88
          "policyAssignmentId": "...",
89
          "policyEffect": "deny"
90
        }
91
      }
92
    ]
93
  }
94
}
95
```
96

97
#### Usage Example
98

99
```python
100
import json
101
from azure.mgmt.core.exceptions import ARMErrorFormat
102

103
# Parse ARM error response
104
error_response = {
105
    "error": {
106
        "code": "InvalidLocation",
107
        "message": "The location 'invalid-region' is not available for subscription.",
108
        "target": "location",
109
        "additionalInfo": [
110
            {
111
                "type": "PolicyViolation", 
112
                "info": {
113
                    "policyDefinitionId": "/subscriptions/.../policyDefinitions/allowed-locations",
114
                    "allowedLocations": ["eastus", "westus", "centralus"]
115
                }
116
            }
117
        ]
118
    }
119
}
120

121
# Create ARM error format
122
arm_error = ARMErrorFormat(error_response)
123

124
print(arm_error.code)        # "InvalidLocation"
125
print(arm_error.message)     # "The location 'invalid-region' is not available for subscription."
126
print(arm_error.target)      # "location"
127

128
# Access additional info
129
for info in arm_error.additional_info:
130
    print(f"Type: {info.type}")
131
    print(f"Info: {info.info}")
132

133
print(str(arm_error))
134
# Output includes both OData v4 format and additional ARM-specific information
135
```
136

137
### Error Response Processing
138

139
When processing ARM error responses, the ARMErrorFormat automatically handles:
140

141
1. **Standard OData v4 Fields**: Extracts code, message, target, details from the error object
142
2. **ARM Extensions**: Processes additionalInfo array into TypedErrorInfo objects  
143
3. **Nested Error Structure**: Handles both direct error objects and error objects wrapped in "error" property
144

145
#### Common ARM Error Types
146

147
ARM operations may include these additional info types:
148

149
- **PolicyViolation**: Policy assignment preventing the operation
150
- **QuotaExceeded**: Resource quota limits reached
151
- **ResourceNotFound**: Referenced resource doesn't exist
152
- **LocationNotAvailable**: Requested region not available
153
- **SkuNotAvailable**: Requested SKU not available in region
154
- **FeatureNotEnabled**: Required feature not enabled for subscription
155

156
#### Integration with Azure Core
157

158
ARMErrorFormat extends Azure Core's ODataV4Format, providing seamless integration:
159

160
```python
161
from azure.core.exceptions import HttpResponseError
162
from azure.mgmt.core.exceptions import ARMErrorFormat
163

164
# Typically used in Azure SDK exception handling
165
try:
166
    # ARM operation that may fail
167
    result = client.some_arm_operation()
168
except HttpResponseError as e:
169
    # Parse ARM-specific error details
170
    if e.response.status_code >= 400:
171
        arm_error = ARMErrorFormat(e.response.json())
172
        
173
        print(f"ARM Error: {arm_error.code}")
174
        print(f"Message: {arm_error.message}")
175
        
176
        # Handle additional ARM-specific info
177
        for info in arm_error.additional_info:
178
            if info.type == "PolicyViolation":
179
                print(f"Policy blocked operation: {info.info}")
180
            elif info.type == "QuotaExceeded":
181
                print(f"Quota exceeded: {info.info}")
182
```
183

184
## Key Features
185

186
### OData v4 Compatibility
187

188
ARMErrorFormat maintains full compatibility with OData v4 error format while adding ARM-specific extensions. This ensures compatibility with existing Azure Core error handling patterns.
189

190
### Structured Additional Information
191

192
Additional error information is parsed into structured TypedErrorInfo objects rather than raw dictionaries, providing type safety and consistent access patterns.
193

194
### Flexible Error Parsing
195

196
Handles various ARM error response formats:
197
- Responses with top-level "error" wrapper
198
- Direct error objects without wrapper  
199
- Missing or empty additionalInfo arrays
200
- Malformed additional info entries (gracefully ignored)
201

202
### Rich String Representation
203

204
Both classes provide detailed string representations suitable for logging and debugging, including formatted JSON output for complex error information.
205

206
## Types
207

208
```python { .api }
209
# Type hints for error handling
210
from typing import Mapping, Any, Sequence
211

212
# Used in TypedErrorInfo
213
InfoMapping = Mapping[str, Any]
214

215
# Used in ARMErrorFormat
216
JsonObject = Mapping[str, Any]
217
```