1. 1use crate::types::AssistantMessage;
2. 2
3. 3#[derive(Debug, Clone, thiserror::Error)]
4. 4pub enum LlmError {
5. 5 #[error("authentication failed: {0}")]
6. 6 Auth(String),
7. 7 #[error("rate limited: {message}")]
8. 8 RateLimit {
9. 9 message: String,
10. 10 retry_after_secs: Option<u64>,
11. 11 },
12. 12 #[error("provider overloaded: {0}")]
13. 13 Overloaded(String),
14. 14 #[error("invalid request: {0}")]
15. 15 InvalidRequest(String),
16. 16 #[error("api error (status {status}): {message}")]
17. 17 Api { status: u16, message: String },
18. 18 #[error("network error: {0}")]
19. 19 Network(String),
20. 20 #[error("response parse error: {0}")]
21. 21 Parse(String),
22. 22 #[error("context budget exceeded: {0}")]
23. 23 Context(String),
24. 24 #[error("aborted before completion")]
25. 25 // Boxed: `AssistantMessage` grew past the threshold where every
26. 26 // `Result<_, LlmError>` in the crate trips `clippy::result_large_err`
27. 27 // (adding `Usage::prefill_ms`/`load_ms` and `AssistantMessage::response_id`
28. 28 // pushed it from ~104 to ~160 bytes).
29. 29 Aborted {
30. 30 partial: Option<Box<AssistantMessage>>,
31. 31 },
32. 32}
33. 33
34. 34/// Provider phrasing, across every adapter, that means "the prompt does not
35. 35/// fit the model's context window" rather than some other malformed
36. 36/// request. Keyed off the provider's own wording rather than a status code
37. 37/// alone, because 400 also covers unrelated validation failures.
38. 38const OVER_LENGTH_MARKERS: [&str; 4] = [
39. 39 "exceeds the model's maximum context length", // Ollama
40. 40 "context_length_exceeded", // OpenAI
41. 41 "maximum context length", // OpenAI
42. 42 "prompt is too long", // Anthropic
43. 43];
44. 44
45. 45impl LlmError {
46. 46 /// Classify a 400-class rejection: over-length phrasing becomes
47. 47 /// `Context` (recoverable by re-planning the working set and retrying),
48. 48 /// everything else stays `InvalidRequest` (a permanent per-request
49. 49 /// failure). Every adapter's `map_status_error` routes its 400 branch
50. 50 /// through this so the distinction is made once, not per provider.
51. 51 pub fn classify_400(message: String) -> Self {
52. 52 let normalized = message.to_ascii_lowercase();
53. 53 if OVER_LENGTH_MARKERS
54. 54 .iter()
55. 55 .any(|marker| normalized.contains(marker))
56. 56 {
57. 57 LlmError::Context(message)
58. 58 } else {
59. 59 LlmError::InvalidRequest(message)
60. 60 }
61. 61 }
62. 62
63. 63 /// Preserve the provider's rejection while adding endpoint-level guidance
64. 64 /// when it explicitly identifies an unsupported tools/reasoning pairing.
65. 65 ///
66. 66 /// This deliberately keys off the provider's response rather than a model
67. 67 /// name table: model capabilities change independently of this binary.
68. 68 pub fn invalid_request_for_endpoint(endpoint: &str, message: impl Into<String>) -> Self {
69. 69 let message = message.into();
70. 70 let normalized = message.to_ascii_lowercase();
71. 71 let tool_reasoning_conflict = normalized.contains("reasoning_effort")
72. 72 && (normalized.contains("function tool") || normalized.contains("function calling"))
73. 73 && normalized.contains("response");
74. 74 if endpoint == "/v1/chat/completions" && tool_reasoning_conflict {
75. 75 return Self::InvalidRequest(format!(
76. 76 "{message}\n\nThe selected route uses {endpoint}, which the provider reports cannot combine this model's current reasoning effort with function tools. Use a Responses-capable route for this model (vak's native OpenAI route is `openai-responses`), or select a Chat Completions-compatible model/configuration with reasoning effort disabled. This is an endpoint capability mismatch, not a transient failure."
77. 77 ));
78. 78 }
79. 79 Self::InvalidRequest(message)
80. 80 }
81. 81
82. 82 pub fn is_retryable(&self) -> bool {
83. 83 matches!(
84. 84 self,
85. 85 LlmError::RateLimit { .. } | LlmError::Overloaded(_) | LlmError::Network(_)
86. 86 ) && !self.is_terminal_quota()
87. 87 }
88. 88
89. 89 /// Some gateways use HTTP 429 for a quota or billing ceiling that will
90. 90 /// not recover during this run. Retrying those errors burns a dispatch
91. 91 /// budget and delays a usable fallback without changing the outcome.
92. 92 pub fn is_terminal_quota(&self) -> bool {
93. 93 let LlmError::RateLimit { message, .. } = self else {
94. 94 return false;
95. 95 };
96. 96 let message = message.to_ascii_lowercase();
97. 97 [
98. 98 "free-models-per-day",
99. 99 "daily quota",
100. 100 "monthly quota",
101. 101 "quota exceeded",
102. 102 "spend limit",
103. 103 "credit limit",
104. 104 "insufficient credits",
105. 105 "billing limit",
106. 106 ]
107. 107 .iter()
108. 108 .any(|marker| message.contains(marker))
109. 109 }
110. 110
111. 111 /// Server-advised wait for RateLimit; None otherwise.
112. 112 pub fn retry_after_secs(&self) -> Option<u64> {
113. 113 match self {
114. 114 LlmError::RateLimit {
115. 115 retry_after_secs, ..
116. 116 } => *retry_after_secs,
117. 117 _ => None,
118. 118 }
119. 119 }
120. 120}
121. 121
122. 122#[cfg(test)]
123. 123mod tests {
124. 124 use super::LlmError;
125. 125
126. 126 #[test]
127. 127 fn terminal_quota_429_is_not_retried() {
128. 128 let error = LlmError::RateLimit {
129. 129 message: "Rate limit exceeded: free-models-per-day".into(),
130. 130 retry_after_secs: None,
131. 131 };
132. 132 assert!(error.is_terminal_quota());
133. 133 assert!(!error.is_retryable());
134. 134 }
135. 135
136. 136 #[test]
137. 137 fn ordinary_rate_limit_remains_retryable() {
138. 138 let error = LlmError::RateLimit {
139. 139 message: "too many requests".into(),
140. 140 retry_after_secs: Some(2),
141. 141 };
142. 142 assert!(!error.is_terminal_quota());
143. 143 assert!(error.is_retryable());
144. 144 }
145. 145
146. 146 #[test]
147. 147 fn chat_completions_tool_reasoning_rejection_explains_the_route_fix() {
148. 148 let error = LlmError::invalid_request_for_endpoint(
149. 149 "/v1/chat/completions",
150. 150 "Function tools with reasoning_effort are not supported for a model in /v1/chat/completions. To use function tools, use /v1/responses or set reasoning_effort to 'none'.",
151. 151 );
152. 152 let rendered = error.to_string();
153. 153 assert!(rendered.contains("openai-responses"));
154. 154 assert!(rendered.contains("endpoint capability mismatch"));
155. 155 }
156. 156
157. 157 #[test]
158. 158 fn unrelated_invalid_request_is_preserved_verbatim() {
159. 159 let error =
160. 160 LlmError::invalid_request_for_endpoint("/v1/chat/completions", "model does not exist");
161. 161 assert_eq!(error.to_string(), "invalid request: model does not exist");
162. 162 }
163. 163
164. 164 #[test]
165. 165 fn classify_400_detects_ollama_over_length_phrasing() {
166. 166 let error = LlmError::classify_400(
167. 167 "request exceeds the model's maximum context length (8192)".into(),
168. 168 );
169. 169 assert!(matches!(error, LlmError::Context(_)));
170. 170 }
171. 171
172. 172 #[test]
173. 173 fn classify_400_detects_openai_context_length_exceeded_code() {
174. 174 let error = LlmError::classify_400(
175. 175 "This model's maximum context length is 8192 tokens. (context_length_exceeded)".into(),
176. 176 );
177. 177 assert!(matches!(error, LlmError::Context(_)));
178. 178 }
179. 179
180. 180 #[test]
181. 181 fn classify_400_detects_openai_maximum_context_length_phrase() {
182. 182 let error = LlmError::classify_400(
183. 183 "your messages resulted in maximum context length exceeded".into(),
184. 184 );
185. 185 assert!(matches!(error, LlmError::Context(_)));
186. 186 }
187. 187
188. 188 #[test]
189. 189 fn classify_400_detects_anthropic_prompt_too_long_phrase() {
190. 190 let error =
191. 191 LlmError::classify_400("prompt is too long: 220000 tokens > 200000 maximum".into());
192. 192 assert!(matches!(error, LlmError::Context(_)));
193. 193 }
194. 194
195. 195 #[test]
196. 196 fn classify_400_leaves_unrelated_rejections_as_invalid_request() {
197. 197 let error = LlmError::classify_400("model does not exist".into());
198. 198 assert!(matches!(error, LlmError::InvalidRequest(_)));
199. 199 }
200. 200}
201. 201