Coverage for src / agent / exceptions.py: 100%

1# Copyright 2025-2026 Microsoft Corporation 

2# 

3# Licensed under the Apache License, Version 2.0 (the "License"); 

4# you may not use this file except in compliance with the License. 

5# You may obtain a copy of the License at 

6# 

7# http://www.apache.org/licenses/LICENSE-2.0 

8# 

9# Unless required by applicable law or agreed to in writing, software 

10# distributed under the License is distributed on an "AS IS" BASIS, 

11# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 

12# See the License for the specific language governing permissions and 

13# limitations under the License. 

14 

15"""Custom exceptions for agent errors. 

16 

17This module provides a hierarchy of exception classes for better error handling 

18and user-friendly error messages. 

19""" 

20 

21 

22class AgentError(Exception): 

23 """Base exception for all agent errors. 

24 

25 This is the root of the exception hierarchy. All custom agent exceptions 

26 should inherit from this class. 

27 """ 

28 

29 pass 

30 

31 

32class ProviderAPIError(AgentError): 

33 """Provider API error (500, 503, 529). 

34 

35 Raised when the LLM provider's API returns a server error, indicating 

36 a temporary issue on the provider's side. 

37 

38 Attributes: 

39 provider: Provider name (anthropic, openai, azure, etc.) 

40 status_code: HTTP status code 

41 message: Error message 

42 request_id: Provider's request ID for debugging (optional) 

43 model: Model name used in the request (optional) 

44 original_error: Original exception from the provider SDK (optional) 

45 """ 

46 

47 def __init__( 

48 self, 

49 provider: str, 

50 status_code: int, 

51 message: str, 

52 request_id: str | None = None, 

53 model: str | None = None, 

54 original_error: Exception | None = None, 

55 ): 

56 """Initialize ProviderAPIError. 

57 

58 Args: 

59 provider: Provider name (anthropic, openai, azure, etc.) 

60 status_code: HTTP status code 

61 message: Error message 

62 request_id: Provider's request ID for debugging 

63 model: Model name used in the request 

64 original_error: Original exception from the provider SDK 

65 """ 

66 self.provider = provider 

67 self.status_code = status_code 

68 self.request_id = request_id 

69 self.model = model 

70 self.original_error = original_error 

71 super().__init__(message) 

72 

73 

74class ProviderAuthError(AgentError): 

75 """Provider authentication error (401, 403). 

76 

77 Raised when the provider rejects the API key or authentication credentials. 

78 

79 Attributes: 

80 provider: Provider name (anthropic, openai, azure, etc.) 

81 status_code: HTTP status code 

82 message: Error message 

83 model: Model name used in the request (optional) 

84 original_error: Original exception from the provider SDK (optional) 

85 """ 

86 

87 def __init__( 

88 self, 

89 provider: str, 

90 status_code: int, 

91 message: str, 

92 model: str | None = None, 

93 original_error: Exception | None = None, 

94 ): 

95 """Initialize ProviderAuthError. 

96 

97 Args: 

98 provider: Provider name (anthropic, openai, azure, etc.) 

99 status_code: HTTP status code 

100 message: Error message 

101 model: Model name used in the request 

102 original_error: Original exception from the provider SDK 

103 """ 

104 self.provider = provider 

105 self.status_code = status_code 

106 self.model = model 

107 self.original_error = original_error 

108 super().__init__(message) 

109 

110 

111class ProviderRateLimitError(AgentError): 

112 """Provider rate limit error (429). 

113 

114 Raised when the provider's rate limit is exceeded. 

115 

116 Attributes: 

117 provider: Provider name (anthropic, openai, azure, etc.) 

118 status_code: HTTP status code 

119 message: Error message 

120 retry_after: Seconds to wait before retrying (optional) 

121 model: Model name used in the request (optional) 

122 original_error: Original exception from the provider SDK (optional) 

123 """ 

124 

125 def __init__( 

126 self, 

127 provider: str, 

128 status_code: int, 

129 message: str, 

130 retry_after: int | None = None, 

131 model: str | None = None, 

132 original_error: Exception | None = None, 

133 ): 

134 """Initialize ProviderRateLimitError. 

135 

136 Args: 

137 provider: Provider name (anthropic, openai, azure, etc.) 

138 status_code: HTTP status code 

139 message: Error message 

140 retry_after: Seconds to wait before retrying 

141 model: Model name used in the request 

142 original_error: Original exception from the provider SDK 

143 """ 

144 self.provider = provider 

145 self.status_code = status_code 

146 self.retry_after = retry_after 

147 self.model = model 

148 self.original_error = original_error 

149 super().__init__(message) 

150 

151 

152class ProviderModelNotFoundError(AgentError): 

153 """Provider model not found error (404). 

154 

155 Raised when the specified model doesn't exist or isn't available. 

156 

157 Attributes: 

158 provider: Provider name (anthropic, openai, azure, etc.) 

159 status_code: HTTP status code 

160 message: Error message 

161 model: Model name that wasn't found 

162 original_error: Original exception from the provider SDK (optional) 

163 """ 

164 

165 def __init__( 

166 self, 

167 provider: str, 

168 status_code: int, 

169 message: str, 

170 model: str | None = None, 

171 original_error: Exception | None = None, 

172 ): 

173 """Initialize ProviderModelNotFoundError. 

174 

175 Args: 

176 provider: Provider name (anthropic, openai, azure, etc.) 

177 status_code: HTTP status code 

178 message: Error message 

179 model: Model name that wasn't found 

180 original_error: Original exception from the provider SDK 

181 """ 

182 self.provider = provider 

183 self.status_code = status_code 

184 self.model = model 

185 self.original_error = original_error 

186 super().__init__(message) 

187 

188 

189class ProviderTimeoutError(AgentError): 

190 """Provider timeout error. 

191 

192 Raised when a request to the provider times out or has network issues. 

193 

194 Attributes: 

195 provider: Provider name (anthropic, openai, azure, etc.) 

196 message: Error message 

197 model: Model name used in the request (optional) 

198 original_error: Original exception from the provider SDK (optional) 

199 """ 

200 

201 def __init__( 

202 self, 

203 provider: str, 

204 message: str, 

205 model: str | None = None, 

206 original_error: Exception | None = None, 

207 ): 

208 """Initialize ProviderTimeoutError. 

209 

210 Args: 

211 provider: Provider name (anthropic, openai, azure, etc.) 

212 message: Error message 

213 model: Model name used in the request 

214 original_error: Original exception from the provider SDK 

215 """ 

216 self.provider = provider 

217 self.model = model 

218 self.original_error = original_error 

219 super().__init__(message) 

220 

221 

222class AgentConfigError(AgentError): 

223 """Agent configuration error. 

224 

225 Raised when there's an issue with the agent's configuration. 

226 

227 This is kept for backward compatibility but is not part of the provider 

228 error handling system. 

229 """ 

230 

231 pass