refactor(rust): centralize transport errors

This commit is contained in:
Yujong Lee 2026-09-09 17:34:08 -07:00
parent 4b03767ec2
commit afc4080e8f
14 changed files with 150 additions and 109 deletions

View file

@ -17,7 +17,7 @@ use std::time::Duration;
use futures_util::stream::{SplitSink, SplitStream};
use futures_util::{Sink, SinkExt, Stream, StreamExt};
use litellm_core::AuthError;
use litellm_core::error::Error;
use litellm_core::error::{Error, TransportError};
use litellm_core::realtime::transformation::RealtimeProviderConfig;
use litellm_core::realtime::types::RealtimeEvent;
use tokio::net::TcpStream;
@ -79,7 +79,7 @@ pub(crate) async fn dial_upstream(
let mut request = url
.as_str()
.into_client_request()
.map_err(|err| Error::Network(err.to_string()))?;
.map_err(|err| TransportError::Network(err.to_string()))?;
// GA realtime: only Authorization. The legacy OpenAI-Beta header triggers
// beta_api_shape_disabled, so we do not send it.
request.headers_mut().insert(
@ -90,7 +90,7 @@ pub(crate) async fn dial_upstream(
let (upstream, _response) = connect_upstream(request)
.await
.map_err(|err| Error::Network(err.to_string()))?;
.map_err(|err| TransportError::Network(err.to_string()))?;
Ok(upstream)
}
@ -104,8 +104,10 @@ pub(crate) async fn read_event(upstream_rx: &mut UpstreamRx) -> Result<RealtimeE
let message = upstream_rx
.next()
.await
.ok_or_else(|| Error::Network("upstream closed before first event".to_string()))?
.map_err(|err| Error::Network(err.to_string()))?;
.ok_or_else(|| {
TransportError::Network("upstream closed before first event".to_string())
})?
.map_err(|err| TransportError::Network(err.to_string()))?;
match message {
Message::Text(text) => {
return serde_json::from_str(&text)
@ -114,9 +116,10 @@ pub(crate) async fn read_event(upstream_rx: &mut UpstreamRx) -> Result<RealtimeE
// Ignore protocol frames (ping/pong) while waiting for the first event.
Message::Ping(_) | Message::Pong(_) => continue,
Message::Close(_) => {
return Err(Error::Network(
return Err(TransportError::Network(
"upstream closed before first event".to_string(),
));
)
.into());
}
_ => continue,
}
@ -157,7 +160,7 @@ where
client_out
.send(outbound)
.await
.map_err(|err| Error::Network(err.to_string()))?;
.map_err(|err| TransportError::Network(err.to_string()))?;
}
}
@ -182,13 +185,13 @@ where
upstream_tx
.send(Message::Text(payload))
.await
.map_err(|err| Error::Network(err.to_string()))?;
.map_err(|err| TransportError::Network(err.to_string()))?;
}
}
// upstream -> client
upstream_message = upstream_rx.next() => {
let Some(message) = upstream_message else { break }; // upstream closed
match message.map_err(|err| Error::Network(err.to_string()))? {
match message.map_err(|err| TransportError::Network(err.to_string()))? {
Message::Text(text) => {
let event: RealtimeEvent = serde_json::from_str(&text)
.map_err(|err| Error::InvalidResponse(err.to_string()))?;
@ -197,7 +200,7 @@ where
client_out
.send(outbound)
.await
.map_err(|err| Error::Network(err.to_string()))?;
.map_err(|err| TransportError::Network(err.to_string()))?;
}
}
Message::Close(_) => break,
@ -312,7 +315,10 @@ mod tests {
)
.await;
assert!(matches!(result, Err(Error::Network(_))));
assert!(matches!(
result,
Err(Error::Transport(TransportError::Network(_)))
));
}
#[test]

View file

@ -13,6 +13,7 @@ use tokio_tungstenite::tungstenite::http::HeaderValue;
use tokio_tungstenite::tungstenite::http::header::{AUTHORIZATION, HeaderName};
use tokio_tungstenite::{MaybeTlsStream, WebSocketStream};
use litellm_core::error::TransportError;
use litellm_core::providers::openai::responses::transformation::OPENAI_RESPONSES_WS_CONFIG;
use litellm_core::responses::types::ResponsesWsEvent;
use litellm_core::responses::websocket::ResponsesWebSocketProviderConfig;
@ -42,7 +43,7 @@ impl ResponsesWebSocketConnection {
) -> Result<Self, Error> {
let mut request = url
.into_client_request()
.map_err(|error| Error::Network(error.to_string()))?;
.map_err(|error| TransportError::Network(error.to_string()))?;
for (name, value) in headers {
let header_name = name
.parse::<HeaderName>()
@ -54,16 +55,18 @@ impl ResponsesWebSocketConnection {
let connect = connect_upstream(request);
let result = match timeout {
Some(timeout) => tokio::time::timeout(timeout, connect).await.map_err(|_| {
Error::Network("Responses WebSocket connection timed out".to_string())
TransportError::Network("Responses WebSocket connection timed out".to_string())
})?,
None => connect.await,
};
let (socket, _) = result.map_err(|error| match *error {
tokio_tungstenite::tungstenite::Error::Http(response) => Error::Http {
status: response.status().as_u16(),
body: String::new(),
},
other => Error::Network(other.to_string()),
tokio_tungstenite::tungstenite::Error::Http(response) => {
Error::from(TransportError::Http {
status: response.status().as_u16(),
body: String::new(),
})
}
other => Error::from(TransportError::Network(other.to_string())),
})?;
Ok(Self {
socket: Arc::new(Mutex::new(Some(socket))),
@ -73,12 +76,14 @@ impl ResponsesWebSocketConnection {
pub async fn send_text(&self, text: String) -> Result<(), Error> {
let mut socket = self.socket.lock().await;
let Some(socket) = socket.as_mut() else {
return Err(Error::Network("Responses WebSocket is closed".to_string()));
return Err(
TransportError::Network("Responses WebSocket is closed".to_string()).into(),
);
};
socket
.send(Message::Text(text))
.await
.map_err(|error| Error::Network(error.to_string()))
.map_err(|error| TransportError::Network(error.to_string()).into())
}
pub async fn recv_text(&self) -> Result<Option<String>, Error> {
@ -93,7 +98,7 @@ impl ResponsesWebSocketConnection {
.map_err(|error| Error::InvalidResponse(error.to_string())),
Some(Ok(Message::Close(_))) | None => Ok(None),
Some(Ok(_)) => Ok(None),
Some(Err(error)) => Err(Error::Network(error.to_string())),
Some(Err(error)) => Err(TransportError::Network(error.to_string()).into()),
}
}
@ -103,7 +108,7 @@ impl ResponsesWebSocketConnection {
socket
.close(None)
.await
.map_err(|error| Error::Network(error.to_string()))?;
.map_err(|error| TransportError::Network(error.to_string()))?;
}
*socket = None;
Ok(())
@ -134,7 +139,7 @@ async fn dial_upstream(
let mut request = url
.as_str()
.into_client_request()
.map_err(|error| Error::Network(error.to_string()))?;
.map_err(|error| TransportError::Network(error.to_string()))?;
request.headers_mut().insert(
AUTHORIZATION,
HeaderValue::from_str(&format!("Bearer {api_key}"))
@ -145,15 +150,17 @@ async fn dial_upstream(
connect_upstream(request),
)
.await
.map_err(|_| Error::Network("Responses WebSocket connection timed out".to_string()))?;
.map_err(|_| TransportError::Network("Responses WebSocket connection timed out".to_string()))?;
result
.map(|(socket, _)| socket)
.map_err(|error| match *error {
tokio_tungstenite::tungstenite::Error::Http(response) => Error::Http {
status: response.status().as_u16(),
body: String::new(),
},
other => Error::Network(other.to_string()),
tokio_tungstenite::tungstenite::Error::Http(response) => {
Error::from(TransportError::Http {
status: response.status().as_u16(),
body: String::new(),
})
}
other => Error::from(TransportError::Network(other.to_string())),
})
}
@ -215,12 +222,12 @@ where
.map_err(|error| Error::InvalidResponse(error.to_string()))?;
upstream_tx.send(Message::Text(payload))
.await
.map_err(|error| Error::Network(error.to_string()))?;
.map_err(|error| TransportError::Network(error.to_string()))?;
}
}
message = upstream_rx.next() => {
let Some(message) = message else { break };
match message.map_err(|error| Error::Network(error.to_string()))? {
match message.map_err(|error| TransportError::Network(error.to_string()))? {
Message::Text(text) => {
let event = serde_json::from_str::<ResponsesWsEvent>(&text)
.map_err(|error| Error::InvalidResponse(error.to_string()))?;
@ -231,7 +238,7 @@ where
{
client_out.send(outbound)
.await
.map_err(|error| Error::Network(error.to_string()))?;
.map_err(|error| TransportError::Network(error.to_string()))?;
}
}
Message::Close(_) => break,
@ -273,7 +280,7 @@ where
upstream_tx
.send(Message::Text(payload))
.await
.map_err(|error| Error::Network(error.to_string()))?;
.map_err(|error| TransportError::Network(error.to_string()))?;
}
}
ResponsesWebSocketStreaming::bidirectional_forward(
@ -348,7 +355,10 @@ mod tests {
let result =
dial_upstream("gpt-5", "sk-test", Some(&format!("wss://127.0.0.1:{port}"))).await;
assert!(matches!(result, Err(Error::Network(_))));
assert!(matches!(
result,
Err(Error::Transport(TransportError::Network(_)))
));
}
async fn websocket_base() -> (String, tokio::task::JoinHandle<()>) {
@ -539,7 +549,10 @@ mod tests {
)
.await
.expect_err("status error");
assert!(matches!(error, Error::Http { status: 401, .. }));
assert!(matches!(
error,
Error::Transport(TransportError::Http { status: 401, .. })
));
server.await.expect("server task");
}
@ -568,7 +581,10 @@ mod tests {
)
.await
.expect_err("status error");
assert!(matches!(error, Error::Http { status: 500, .. }));
assert!(matches!(
error,
Error::Transport(TransportError::Http { status: 500, .. })
));
server.await.expect("server task");
}
}

View file

@ -10,6 +10,7 @@ use axum::http::header::{CACHE_CONTROL, CONTENT_TYPE, HeaderMap, HeaderValue};
use axum::response::{IntoResponse, Response};
use axum::routing::post;
use litellm_core::Error;
use litellm_core::error::TransportError;
use serde_json::{Map, Value};
use crate::auth::RequireMasterKey;
@ -115,9 +116,11 @@ impl IntoResponse for MessagesRouteError {
Error::OcrResponse(_)
| Error::OcrPolling(_)
| Error::ChatResponse(_)
| Error::Http { .. }
| Error::Network(_)
| Error::Connect(_)
| Error::Transport(
TransportError::Http { .. }
| TransportError::Network(_)
| TransportError::Connect(_),
)
| Error::InvalidResponse(_)
| Error::InvalidType { .. }
| Error::MissingField(_) => (

View file

@ -297,7 +297,7 @@ async fn reducto_upload_error_body_is_truncated() {
let error = ocr(request).await.expect_err("upload should fail");
assert!(
matches!(error, Error::Http { status: 500, body } if body.chars().count() < 300 && body.ends_with("... (truncated)"))
matches!(error, Error::Transport(litellm_core::error::TransportError::Http { status: 500, body }) if body.chars().count() < 300 && body.ends_with("... (truncated)"))
);
server.await.expect("server task completes");
}
@ -439,7 +439,10 @@ async fn ocr_lifecycle_runs_failure_hook_on_provider_error() {
let call = call.with_subscriber(trace.dispatcher());
let err = call.await.expect_err("provider error propagates");
assert!(matches!(err, Error::Http { status: 500, .. }));
assert!(matches!(
err,
Error::Transport(litellm_core::error::TransportError::Http { status: 500, .. })
));
server.await.expect("server task completes");
assert_eq!(
logger.events(),

View file

@ -23,17 +23,18 @@ pub async fn execute_audio_transcription_provider_call(
}
let response = http_request(request_builder)
.await
.map_err(crate::error::TransportError::before_request)?;
.map_err(crate::error::TransportError::from_reqwest_before_dispatch)?;
let status = response.status();
let text = response
.text()
.await
.map_err(crate::error::TransportError::from)?;
if !status.is_success() {
return Err(Error::Http {
return Err(crate::error::TransportError::Http {
status: status.as_u16(),
body: truncate_error_body(&text),
});
}
.into());
}
let response_json = serde_json::from_str(&text)
.map_err(|error| Error::InvalidResponse(format!("invalid audio response JSON: {error}")))?;

View file

@ -383,13 +383,20 @@ mod tests {
"request".to_string(),
&hooks,
|_request| async move {
Err::<String, Error>(Error::Network("provider down".to_string()))
Err::<String, Error>(
crate::error::TransportError::Network("provider down".to_string()).into(),
)
},
)
.await
.expect_err("call fails");
assert_eq!(error, Error::Network("provider down".to_string()));
assert_eq!(
error,
Error::Transport(crate::error::TransportError::Network(
"provider down".to_string()
))
);
assert_eq!(hooks.events(), vec!["pre_call", "during_call", "failure"]);
}

View file

@ -32,7 +32,7 @@ pub(super) async fn execute_chat_completions_provider_call(
let response = http_request(request_builder)
.await
.map_err(TransportError::before_request)?;
.map_err(TransportError::from_reqwest_before_dispatch)?;
let status = response.status();
let text = response
@ -41,10 +41,11 @@ pub(super) async fn execute_chat_completions_provider_call(
.map_err(|err| Error::from(TransportError::from(err)))?;
if !status.is_success() {
return Err(Error::Http {
return Err(TransportError::Http {
status: status.as_u16(),
body: truncate_error_body(&text),
});
}
.into());
}
let body: Value = serde_json::from_str(&text)

View file

@ -29,17 +29,8 @@ pub enum Error {
InvalidRequest(String),
#[error(transparent)]
Auth(#[from] AuthError),
#[error("upstream request failed with status {status}: {body}")]
Http { status: u16, body: String },
#[error("upstream network error: {0}")]
Network(String),
/// The provider was never reached: DNS, TCP, TLS or proxy setup failed
/// before any byte of the request went out. Nothing was billed, so a host
/// that keeps a reference implementation can serve the request itself.
/// A timeout is deliberately not this, since the provider may have received
/// and answered the request already.
#[error("could not reach the provider: {0}")]
Connect(String),
#[error(transparent)]
Transport(#[from] TransportError),
#[error("routing error: {0}")]
Routing(String),
/// The request is outside the surface this route covers in Rust. Hosts that
@ -87,12 +78,13 @@ pub enum TransportError {
Http { status: u16, body: String },
#[error("upstream network error: {0}")]
Network(String),
/// The provider was never reached, so a host can safely retry on another path.
#[error("could not reach the provider: {0}")]
Connect(String),
}
impl TransportError {
pub fn before_request(error: reqwest::Error) -> Self {
pub fn from_reqwest_before_dispatch(error: reqwest::Error) -> Self {
let before_dispatch = !error.is_timeout() && (error.is_connect() || error.is_builder());
let message = error.without_url().to_string();
if before_dispatch {
@ -109,16 +101,6 @@ impl From<reqwest::Error> for TransportError {
}
}
impl From<TransportError> for Error {
fn from(error: TransportError) -> Self {
match error {
TransportError::Http { status, body } => Self::Http { status, body },
TransportError::Network(message) => Self::Network(message),
TransportError::Connect(message) => Self::Connect(message),
}
}
}
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum ErrorKind {
InvalidType,
@ -150,12 +132,13 @@ impl Error {
}
Self::InvalidProvider(_) => ErrorKind::InvalidProvider,
Self::Auth(_) => ErrorKind::Auth,
Self::Http { .. } => ErrorKind::Http,
Self::Network(_) | Self::OcrPolling(OcrPollingError::PollTimeout) => ErrorKind::Network,
Self::Transport(TransportError::Http { .. }) => ErrorKind::Http,
Self::Transport(TransportError::Network(_))
| Self::OcrPolling(OcrPollingError::PollTimeout) => ErrorKind::Network,
Self::OcrPolling(OcrPollingError::PollOrigin | OcrPollingError::PollLocation) => {
ErrorKind::InvalidResponse
}
Self::Connect(_) => ErrorKind::Connect,
Self::Transport(TransportError::Connect(_)) => ErrorKind::Connect,
Self::Routing(_) => ErrorKind::Routing,
Self::Unsupported(_) => ErrorKind::Unsupported,
}
@ -166,6 +149,17 @@ impl Error {
mod tests {
use super::*;
#[test]
fn transport_error_is_exposed_without_an_extra_message_prefix() {
let error = Error::from(TransportError::Network("connection reset".to_string()));
assert_eq!(error.kind(), ErrorKind::Network);
assert_eq!(
error.to_string(),
"upstream network error: connection reset"
);
}
#[tokio::test]
async fn transport_errors_remove_urls_and_keep_dispatch_context() {
let error = reqwest::Client::builder()
@ -176,7 +170,7 @@ mod tests {
.send()
.await
.expect_err("invalid port");
let error = TransportError::before_request(error);
let error = TransportError::from_reqwest_before_dispatch(error);
assert!(matches!(error, TransportError::Connect(_)));
assert!(!error.to_string().contains("secret"));
assert!(!error.to_string().contains("private"));
@ -218,7 +212,7 @@ mod tests {
let error = response.expect_err("server does not respond");
assert!(error.is_timeout());
assert!(matches!(
TransportError::before_request(error),
TransportError::from_reqwest_before_dispatch(error),
TransportError::Network(_)
));
}

View file

@ -22,7 +22,7 @@ pub(super) async fn execute_messages_provider_call(
let response = http_request(request_builder)
.await
.map_err(crate::error::TransportError::before_request)?;
.map_err(crate::error::TransportError::from_reqwest_before_dispatch)?;
let status = response.status();
let text = response
@ -31,10 +31,11 @@ pub(super) async fn execute_messages_provider_call(
.map_err(crate::error::TransportError::from)?;
if !status.is_success() {
return Err(Error::Http {
return Err(crate::error::TransportError::Http {
status: status.as_u16(),
body: truncate_error_body(&text),
});
}
.into());
}
let response = serde_json::from_str(&text)
@ -62,17 +63,18 @@ pub(super) async fn execute_messages_provider_stream(
let response = http_request(request_builder)
.await
.map_err(crate::error::TransportError::before_request)?;
.map_err(crate::error::TransportError::from_reqwest_before_dispatch)?;
let status = response.status();
if !status.is_success() {
let text = response
.text()
.await
.map_err(crate::error::TransportError::from)?;
return Err(Error::Http {
return Err(crate::error::TransportError::Http {
status: status.as_u16(),
body: truncate_error_body(&text),
});
}
.into());
}
Ok(response)
}

View file

@ -19,7 +19,7 @@ pub struct OcrClient {
}
impl OcrClient {
pub fn new(provider_http: reqwest::Client) -> Result<Self, Error> {
pub fn new(provider_http: reqwest::Client) -> Result<Self, TransportError> {
let document_fetcher = MediaFetcher::new().map_err(TransportError::from)?;
Ok(Self {
provider_http,
@ -55,19 +55,16 @@ impl OcrClient {
}
pub async fn ocr(request: OcrRequest) -> Result<OcrResponseData, Error> {
static CLIENT: OnceLock<Result<OcrClient, String>> = OnceLock::new();
static CLIENT: OnceLock<Result<OcrClient, TransportError>> = OnceLock::new();
let client = CLIENT
.get_or_init(|| {
reqwest::Client::builder()
.connect_timeout(Duration::from_secs(OCR_CONNECT_TIMEOUT_SECS))
.build()
.map_err(|error| error.to_string())
.and_then(|provider_http| {
OcrClient::new(provider_http).map_err(|error| error.to_string())
})
.map_err(TransportError::from)
.and_then(OcrClient::new)
})
.as_ref()
.map_err(|error| TransportError::Network(error.clone()))?;
.clone()?;
client.perform(request).await
}

View file

@ -770,7 +770,10 @@ mod round_trip {
.expect_err("upstream rejects");
handle.await.expect("server task");
assert!(
matches!(err, Error::Http { status: 429, .. }),
matches!(
err,
Error::Transport(crate::error::TransportError::Http { status: 429, .. })
),
"expected a 429, got {err:?}"
);
}
@ -794,7 +797,10 @@ mod round_trip {
.await
.expect_err("nothing is listening");
assert!(
matches!(err, Error::Connect(_)),
matches!(
err,
Error::Transport(crate::error::TransportError::Connect(_))
),
"expected a pre-send connect failure, got {err:?}"
);
}

View file

@ -420,7 +420,10 @@ async fn messages_maps_provider_error_status_to_http_error() {
.await
.expect_err("provider error propagates");
assert!(matches!(err, Error::Http { status: 401, .. }));
assert!(matches!(
err,
Error::Transport(crate::error::TransportError::Http { status: 401, .. })
));
}
#[tokio::test]

View file

@ -1,4 +1,4 @@
use litellm_core::error::{Error, ErrorKind};
use litellm_core::error::{Error, ErrorKind, TransportError};
use pyo3::exceptions::{PyRuntimeError, PyValueError};
use pyo3::prelude::*;
@ -39,7 +39,7 @@ pub(crate) fn core_error_to_pyerr(err: Error) -> PyErr {
/// on its own path; anything after it is not, because the provider has already
/// done the work and billed for it.
pub(crate) fn chat_completions_error_to_pyerr(err: Error) -> PyErr {
if let Error::Http { status, body } = err {
if let Error::Transport(TransportError::Http { status, body }) = err {
return RustUpstreamError::new_err((status, format!("{status}: {body}")));
}
match err.kind() {
@ -69,7 +69,9 @@ pub(crate) fn ocr_error_to_pyerr(err: Error) -> PyErr {
| Error::OcrRequest(litellm_core::ocr::error::OcrRequestError::MissingField(
"document_url" | "image_url",
)) => PyValueError::new_err("Document URL is required"),
Error::Http { status, body } => RustUpstreamError::new_err((status, body)),
Error::Transport(TransportError::Http { status, body }) => {
RustUpstreamError::new_err((status, body))
}
other => core_error_to_pyerr(other),
}
}
@ -87,10 +89,13 @@ mod ocr_error_tests {
assert!(mapped.is_instance_of::<PyValueError>(py));
assert_eq!(mapped.value(py).to_string(), "Document URL is required");
}
let mapped = ocr_error_to_pyerr(Error::Http {
status: 429,
body: r#"{"message":"rate limited"}"#.to_string(),
});
let mapped = ocr_error_to_pyerr(
TransportError::Http {
status: 429,
body: r#"{"message":"rate limited"}"#.to_string(),
}
.into(),
);
assert!(mapped.is_instance_of::<RustUpstreamError>(py));
let args: (u16, String) = mapped
.value(py)

View file

@ -4,17 +4,14 @@ use litellm_core::error::{Error, TransportError};
use litellm_core::ocr::OcrClient;
pub(crate) fn ocr_client() -> Result<OcrClient, Error> {
static CLIENT: OnceLock<Result<OcrClient, String>> = OnceLock::new();
static CLIENT: OnceLock<Result<OcrClient, TransportError>> = OnceLock::new();
CLIENT
.get_or_init(|| {
reqwest::Client::builder()
.build()
.map_err(|error| error.to_string())
.and_then(|provider_http| {
OcrClient::new(provider_http).map_err(|error| error.to_string())
})
.map_err(TransportError::from)
.and_then(OcrClient::new)
})
.as_ref()
.cloned()
.map_err(|error| TransportError::Network(error.clone()).into())
.clone()
.map_err(Error::from)
}