1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
// Error variants are documented through `thiserror`'s `#[error("...")]`
// messages, which double as user-facing display strings and rustdoc-style
// summaries. `missing_docs` would force us to duplicate those messages.
#![allow(missing_docs)]
use std::time::Duration;
use serde::{Deserialize, Serialize};
/// Error response from an OpenAI-compatible API.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub(crate) struct ErrorResponse {
error: ApiError,
}
/// Inner error object.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub(crate) struct ApiError {
message: String,
#[serde(default)]
code: Option<String>,
}
/// All errors that can occur when using `liter-llm`.
#[derive(Debug, thiserror::Error)]
#[non_exhaustive]
pub enum LiterLlmError {
/// `status` preserves the exact HTTP status code received (401 or 403).
#[error("authentication failed: {message}")]
Authentication { message: String, status: u16 },
#[error("rate limited: {message}")]
RateLimited {
message: String,
retry_after: Option<Duration>,
},
/// `status` preserves the exact HTTP status code received (400, 405, 413, 422, …).
#[error("bad request: {message}")]
BadRequest { message: String, status: u16 },
#[error("context window exceeded: {message}")]
ContextWindowExceeded { message: String },
#[error("content policy violation: {message}")]
ContentPolicy { message: String },
#[error("not found: {message}")]
NotFound { message: String },
/// `status` preserves the exact HTTP status code received (500, or other 5xx not covered
/// by `ServiceUnavailable`).
#[error("server error: {message}")]
ServerError { message: String, status: u16 },
/// `status` preserves the exact HTTP status code received (502, 503, or 504).
#[error("service unavailable: {message}")]
ServiceUnavailable { message: String, status: u16 },
#[error("request timeout")]
Timeout,
#[cfg(any(feature = "native-http", feature = "wasm-http"))]
#[error(transparent)]
Network(#[from] reqwest::Error),
/// A catch-all for errors that occur during streaming response processing.
///
/// This variant covers multiple sub-conditions including UTF-8 decoding
/// failures, CRC/checksum mismatches (AWS EventStream), JSON parse errors
/// in individual SSE chunks, and buffer overflow conditions. The `message`
/// field contains a human-readable description of the specific failure.
#[error("streaming error: {message}")]
Streaming { message: String },
#[error("provider {provider} does not support {endpoint}")]
EndpointNotSupported { endpoint: String, provider: String },
#[error("invalid header {name:?}: {reason}")]
InvalidHeader { name: String, reason: String },
#[error("serialization error: {0}")]
Serialization(
#[from]
#[cfg_attr(alef, alef(skip))]
serde_json::Error,
),
#[error("budget exceeded: {message}")]
BudgetExceeded { message: String, model: Option<String> },
#[error("hook rejected: {message}")]
HookRejected { message: String },
/// An internal logic error (e.g. unexpected Tower response variant).
///
/// This should never surface in normal operation — if it does, it
/// indicates a bug in the library.
#[error("internal error: {message}")]
InternalError { message: String },
/// An outbound request was blocked by the active [`crate::provider::OutboundPolicy`].
///
/// Returned when `register_custom_provider` is called with a `base_url` that
/// violates the policy (e.g. a private-range IP under `DenyPrivate`), or when
/// the per-connection DNS resolver detects a forbidden address at connect time.
#[error("outbound request to {url} forbidden: {reason}")]
OutboundForbidden { url: String, reason: String },
}
impl LiterLlmError {
/// Returns the canonical HTTP status code associated with this error.
///
/// Maps error variants to their originating HTTP status code as set by
/// [`LiterLlmError::from_status`]. Used by e2e assertions that check
/// `error.status_code` against the expected HTTP status.
#[must_use]
pub fn status_code(&self) -> u16 {
match self {
Self::Authentication { status, .. } => *status,
Self::RateLimited { .. } => 429,
Self::BadRequest { status, .. } => *status,
Self::ContextWindowExceeded { .. } => 400,
Self::ContentPolicy { .. } => 400,
Self::NotFound { .. } => 404,
Self::ServerError { status, .. } => *status,
Self::ServiceUnavailable { status, .. } => *status,
Self::Timeout => 408,
#[cfg(any(feature = "native-http", feature = "wasm-http"))]
Self::Network(_) => 0,
Self::Streaming { .. } => 0,
Self::EndpointNotSupported { .. } => 400,
Self::InvalidHeader { .. } => 400,
Self::Serialization(_) => 0,
Self::BudgetExceeded { .. } => 0,
Self::HookRejected { .. } => 0,
Self::InternalError { .. } => 0,
Self::OutboundForbidden { .. } => 0,
}
}
/// Returns `true` for errors that are worth retrying on a different service
/// or deployment (transient failures).
///
/// Used by [`crate::tower::fallback::FallbackService`] and
/// [`crate::tower::router::Router`] to decide whether to route to an
/// alternative endpoint.
#[must_use]
pub fn is_transient(&self) -> bool {
match self {
Self::RateLimited { .. } | Self::ServiceUnavailable { .. } | Self::Timeout | Self::ServerError { .. } => {
true
}
#[cfg(any(feature = "native-http", feature = "wasm-http"))]
Self::Network(_) => true,
_ => false,
}
}
/// Return the OpenTelemetry `error.type` string for this error variant.
///
/// Used by the tracing middleware to record the `error.type` span attribute
/// on failed requests per the GenAI semantic conventions.
#[must_use]
pub fn error_type(&self) -> &'static str {
match self {
Self::Authentication { .. } => "Authentication",
Self::RateLimited { .. } => "RateLimited",
Self::BadRequest { .. } => "BadRequest",
Self::ContextWindowExceeded { .. } => "ContextWindowExceeded",
Self::ContentPolicy { .. } => "ContentPolicy",
Self::NotFound { .. } => "NotFound",
Self::ServerError { .. } => "ServerError",
Self::ServiceUnavailable { .. } => "ServiceUnavailable",
Self::Timeout => "Timeout",
#[cfg(any(feature = "native-http", feature = "wasm-http"))]
Self::Network(_) => "Network",
Self::Streaming { .. } => "Streaming",
Self::EndpointNotSupported { .. } => "EndpointNotSupported",
Self::InvalidHeader { .. } => "InvalidHeader",
Self::Serialization(_) => "Serialization",
Self::BudgetExceeded { .. } => "BudgetExceeded",
Self::HookRejected { .. } => "HookRejected",
Self::InternalError { .. } => "InternalError",
Self::OutboundForbidden { .. } => "OutboundForbidden",
}
}
/// Create from an HTTP status code, an API error response body, and an
/// optional `Retry-After` duration already parsed from the response header.
///
/// The `retry_after` value is forwarded into [`LiterLlmError::RateLimited`]
/// so callers can honour the server-requested delay without re-parsing the
/// header.
pub(crate) fn from_status(status: u16, body: &str, retry_after: Option<Duration>) -> Self {
let parsed = serde_json::from_str::<ErrorResponse>(body).ok();
let code = parsed.as_ref().and_then(|r| r.error.code.clone());
let message = parsed.map(|r| r.error.message).unwrap_or_else(|| body.to_string());
match status {
401 | 403 => Self::Authentication { message, status },
429 => Self::RateLimited { message, retry_after },
400 | 422 => {
// Check the structured `code` field first — it is more reliable
// than substring matching on the human-readable message.
if code.as_deref() == Some("context_length_exceeded") {
Self::ContextWindowExceeded { message }
} else if code.as_deref() == Some("content_policy_violation")
|| code.as_deref() == Some("content_filter")
{
Self::ContentPolicy { message }
}
// Fall back to message-based heuristics for providers that do not
// populate the `code` field.
else if message.contains("context_length_exceeded")
|| message.contains("context window")
|| message.contains("maximum context length")
{
Self::ContextWindowExceeded { message }
} else if message.contains("content_policy") || message.contains("content_filter") {
Self::ContentPolicy { message }
} else {
Self::BadRequest { message, status }
}
}
404 => Self::NotFound { message },
405 | 413 => Self::BadRequest { message, status },
408 => Self::Timeout,
500 => Self::ServerError { message, status },
502..=504 => Self::ServiceUnavailable { message, status },
// Map remaining 4xx codes to BadRequest (client errors) and
// everything else (5xx, unknown) to ServerError.
400..=499 => Self::BadRequest { message, status },
_ => Self::ServerError { message, status },
}
}
}
#[cfg_attr(alef, alef(skip))]
pub type Result<T> = std::result::Result<T, LiterLlmError>;