Skip to content

Switchyard lets LLM applications route traffic across models and providers while preserving native OpenAI and Anthropic API compatibility - enabling flexible model selection, benchmarking, and cost/performance optimization.

Rust

refactor(protocol): use typed HTTP status codes (#457)

Bhuvan Agrawal05533a5cdd22
diff --git a/Cargo.lock b/Cargo.lock
index 3d0ea85f6..b8410e755 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -2269,6 +2269,7 @@ version = "0.2.0"
dependencies = [
"async-trait",
"futures",
+ "http",
"jsonptr",
"jsonschema",
"opentelemetry",
diff --git a/crates/libsy-llm-client/src/client.rs b/crates/libsy-llm-client/src/client.rs
index 2751ccfd4..4d29f9763 100644
--- a/crates/libsy-llm-client/src/client.rs
+++ b/crates/libsy-llm-client/src/client.rs
@@ -9,6 +9,7 @@ use std::time::{Duration, SystemTime};
use async_trait::async_trait;
use futures_util::StreamExt;
+use http::StatusCode;
use reqwest::RequestBuilder;
use reqwest::header::{HeaderMap, RETRY_AFTER};
use serde_json::{Map, Value};
@@ -262,7 +263,7 @@ impl TranslatingLlmClient {
let will_retry = attempt < max_retries && failure.is_retryable();
span.record("outcome", "error");
if let Some(status) = failure.status {
- span.record("status_code", status);
+ span.record("status_code", status.as_u16());
}
span.record("will_retry", will_retry);
if !will_retry {
@@ -325,7 +326,7 @@ impl TranslatingLlmClient {
metrics::record_upstream_attempt(None);
return Err(AttemptFailure {
error: convert_reqwest_error(error),
- status: Some(status.as_u16()),
+ status: Some(status),
retry_after: None,
});
}
@@ -344,7 +345,7 @@ impl TranslatingLlmClient {
metrics::record_upstream_attempt(None);
return Err(AttemptFailure {
error: convert_reqwest_error(error),
- status: Some(status.as_u16()),
+ status: Some(status),
retry_after,
});
}
@@ -358,14 +359,11 @@ impl TranslatingLlmClient {
message: body,
}
} else {
- LlmClientError::UpstreamHttp {
- status: status.as_u16(),
- body,
- }
+ LlmClientError::UpstreamHttp { status, body }
};
Err(AttemptFailure {
error,
- status: Some(status.as_u16()),
+ status: Some(status),
retry_after,
})
}
@@ -564,7 +562,7 @@ impl EncodedResponse {
// attempt telemetry and delay selection.
struct AttemptFailure {
error: LlmClientError,
- status: Option<u16>,
+ status: Option<StatusCode>,
retry_after: Option<Duration>,
}
@@ -573,7 +571,7 @@ impl AttemptFailure {
match &self.error {
LlmClientError::Transport { .. } | LlmClientError::Timeout { .. } => true,
LlmClientError::UpstreamHttp { status, .. } => {
- metrics::is_retryable_http_status(*status)
+ metrics::is_retryable_http_status(status.as_u16())
}
_ => false,
}
@@ -1500,7 +1498,10 @@ mod tests {
};
assert!(matches!(
error,
- LlmClientError::UpstreamHttp { status: 500, .. }
+ LlmClientError::UpstreamHttp {
+ status: StatusCode::INTERNAL_SERVER_ERROR,
+ ..
+ }
));
Ok(())
}
@@ -1562,7 +1563,7 @@ mod tests {
assert!(matches!(
error,
LlmClientError::UpstreamHttp {
- status: 401,
+ status: StatusCode::UNAUTHORIZED,
body
} if body == "invalid key"
));
@@ -1598,7 +1599,7 @@ mod tests {
assert!(matches!(
error,
LlmClientError::UpstreamHttp {
- status: 500,
+ status: StatusCode::INTERNAL_SERVER_ERROR,
body
} if body == "attempt 3"
));
@@ -1651,7 +1652,14 @@ mod tests {
};
assert!(transport.is_retryable());
- for status in [408, 429, 500, 503, 599] {
+ for status in [
+ StatusCode::REQUEST_TIMEOUT,
+ StatusCode::TOO_MANY_REQUESTS,
+ StatusCode::INTERNAL_SERVER_ERROR,
+ StatusCode::SERVICE_UNAVAILABLE,
+ StatusCode::from_u16(599)
+ .expect("599 is a syntactically valid HTTP code in the http crate"),
+ ] {
let failure = AttemptFailure {
error: LlmClientError::UpstreamHttp {
status,
@@ -1662,7 +1670,13 @@ mod tests {
};
assert!(failure.is_retryable(), "HTTP {status} should retry");
}
- for status in [400, 401, 409, 600] {
+ for status in [
+ StatusCode::BAD_REQUEST,
+ StatusCode::UNAUTHORIZED,
+ StatusCode::CONFLICT,
+ StatusCode::from_u16(600)
+ .expect("600 is a syntactically valid HTTP code in the http crate"),
+ ] {
let failure = AttemptFailure {
error: LlmClientError::UpstreamHttp {
status,
@@ -1688,7 +1702,7 @@ mod tests {
model: ModelId::from("gpt"),
message: "too long".to_string(),
},
- status: Some(400),
+ status: Some(StatusCode::BAD_REQUEST),
retry_after: None,
};
assert!(!context_window.is_retryable());
diff --git a/crates/libsy-llm-client/src/observability.rs b/crates/libsy-llm-client/src/observability.rs
index c02475b4b..3c62d3a6d 100644
--- a/crates/libsy-llm-client/src/observability.rs
+++ b/crates/libsy-llm-client/src/observability.rs
@@ -191,7 +191,7 @@ fn llm_client_error_type(error: &LlmClientError) -> Cow<'static, str> {
LlmClientError::Transport { .. } => Cow::Borrowed("transport"),
LlmClientError::Timeout { .. } => Cow::Borrowed("timeout"),
LlmClientError::ContextWindowExceeded { .. } => Cow::Borrowed("context_window_exceeded"),
- LlmClientError::UpstreamHttp { status, .. } => Cow::Owned(status.to_string()),
+ LlmClientError::UpstreamHttp { status, .. } => Cow::Owned(status.as_str().to_owned()),
LlmClientError::InvalidResponse { .. } => Cow::Borrowed("invalid_response"),
LlmClientError::Ffi { .. } => Cow::Borrowed("ffi"),
_ => Cow::Borrowed("_OTHER"),
diff --git a/crates/libsy-llm-client/src/run.rs b/crates/libsy-llm-client/src/run.rs
index 9ef133550..0319f1d8a 100644
--- a/crates/libsy-llm-client/src/run.rs
+++ b/crates/libsy-llm-client/src/run.rs
@@ -17,6 +17,7 @@ use std::collections::HashMap;
use std::sync::Arc;
use std::time::{Duration, Instant};
+use http::StatusCode;
use parking_lot::Mutex;
use switchyard_libsy::{Algorithm, CallModel, LibsyError, Result, drive};
use switchyard_protocol::{
@@ -265,7 +266,10 @@ fn fallback_reason(error: &LibsyError) -> Option<RoutingFallbackReason> {
Some(RoutingFallbackReason::Unavailable)
}
LlmClientError::UpstreamHttp { status, .. }
- if matches!(*status, 403 | 408 | 429) || (500..=599).contains(status) =>
+ if matches!(
+ *status,
+ StatusCode::FORBIDDEN | StatusCode::REQUEST_TIMEOUT | StatusCode::TOO_MANY_REQUESTS
+ ) || status.is_server_error() =>
{
Some(RoutingFallbackReason::Unavailable)
}
@@ -353,6 +357,7 @@ mod tests {
use super::*;
use async_trait::async_trait;
use futures::StreamExt;
+ use http::StatusCode;
use switchyard_libsy::Driver;
use switchyard_protocol::{
LlmResponse, LlmResponseChunk, LlmResponseStreamEvent, completion_text, text_request,
@@ -403,7 +408,7 @@ mod tests {
message: "too long".to_string(),
}),
FirstOutcome::Unauthorized => Err(LlmClientError::UpstreamHttp {
- status: 401,
+ status: StatusCode::UNAUTHORIZED,
body: "unauthorized".to_string(),
}),
FirstOutcome::StreamSuccess => Ok(stream_response(vec![
@@ -485,7 +490,13 @@ mod tests {
})),
Some(RoutingFallbackReason::ContextWindow)
);
- for status in [403, 408, 429, 500, 599] {
+ for status in [
+ StatusCode::FORBIDDEN,
+ StatusCode::REQUEST_TIMEOUT,
+ StatusCode::TOO_MANY_REQUESTS,
+ StatusCode::INTERNAL_SERVER_ERROR,
+ StatusCode::from_u16(599).expect("599 is a valid status"),
+ ] {
assert_eq!(
fallback_reason(&error(LlmClientError::UpstreamHttp {
status,
@@ -494,7 +505,14 @@ mod tests {
Some(RoutingFallbackReason::Unavailable)
);
}
- for status in [400, 401, 404, 409, 499, 600] {
+ for status in [
+ StatusCode::BAD_REQUEST,
+ StatusCode::UNAUTHORIZED,
+ StatusCode::NOT_FOUND,
+ StatusCode::CONFLICT,
+ StatusCode::from_u16(499).expect("499 is a valid status"),
+ StatusCode::from_u16(600).expect("600 is a valid status"),
+ ] {
assert_eq!(
fallback_reason(&error(LlmClientError::UpstreamHttp {
status,
@@ -528,7 +546,10 @@ mod tests {
assert!(matches!(
result,
Err(LibsyError::ClientCall {
- source: LlmClientError::UpstreamHttp { status: 401, .. },
+ source: LlmClientError::UpstreamHttp {
+ status: StatusCode::UNAUTHORIZED,
+ ..
+ },
..
})
));
diff --git a/crates/libsy-llm-client/tests/observability.rs b/crates/libsy-llm-client/tests/observability.rs
index ec0882a88..2eaf8609b 100644
--- a/crates/libsy-llm-client/tests/observability.rs
+++ b/crates/libsy-llm-client/tests/observability.rs
@@ -376,7 +376,7 @@ impl RoutedLlmClient for JudgeClient {
}
match &self.outcome {
JudgeOutcome::CallFailure => Err(LlmClientError::UpstreamHttp {
- status: 500,
+ status: http::StatusCode::INTERNAL_SERVER_ERROR,
body: "server error".to_string(),
}),
JudgeOutcome::Reply(text) => Ok(Response {
diff --git a/crates/libsy/Cargo.toml b/crates/libsy/Cargo.toml
index f97d06a80..5ba5423b2 100644
--- a/crates/libsy/Cargo.toml
+++ b/crates/libsy/Cargo.toml
@@ -40,3 +40,4 @@ tracing-opentelemetry.workspace = true
opentelemetry_sdk = { version = "0.32", features = ["metrics", "testing", "trace"] }
tokio.workspace = true
tracing-subscriber.workspace = true
+http.workspace = true
diff --git a/crates/libsy/src/algorithms/util/llm_judge.rs b/crates/libsy/src/algorithms/util/llm_judge.rs
index 6657207e6..a89f2f5a7 100644
--- a/crates/libsy/src/algorithms/util/llm_judge.rs
+++ b/crates/libsy/src/algorithms/util/llm_judge.rs
@@ -284,9 +284,7 @@ fn client_error_reason(error: &LlmClientError) -> &'static str {
match error {
LlmClientError::Timeout { .. } => "timeout",
LlmClientError::Transport { .. } => "transport",
- LlmClientError::UpstreamHttp { status, .. } if (500..=599).contains(status) => {
- "upstream_5xx"
- }
+ LlmClientError::UpstreamHttp { status, .. } if status.is_server_error() => "upstream_5xx",
LlmClientError::UpstreamHttp { .. } => "upstream_non_5xx",
LlmClientError::InvalidResponse { .. } | LlmClientError::ResponseTranslation(_) => {
"invalid_response"
@@ -347,6 +345,7 @@ mod tests {
use super::*;
use futures::StreamExt;
+ use http::StatusCode;
use serde::Deserialize;
use switchyard_protocol::{ContentBlock, LlmClientError, text_request, text_response};
@@ -615,14 +614,14 @@ mod tests {
),
(
LlmClientError::UpstreamHttp {
- status: 500,
+ status: StatusCode::INTERNAL_SERVER_ERROR,
body: "server error".to_string(),
},
"upstream_5xx",
),
(
LlmClientError::UpstreamHttp {
- status: 302,
+ status: StatusCode::FOUND,
body: "redirect".to_string(),
},
"upstream_non_5xx",
diff --git a/crates/protocol/src/client.rs b/crates/protocol/src/client.rs
index f98155f16..dd9f29236 100644
--- a/crates/protocol/src/client.rs
+++ b/crates/protocol/src/client.rs
@@ -81,7 +81,7 @@ pub enum LlmClientError {
#[error("upstream returned HTTP {status}: {body}")]
UpstreamHttp {
/// Upstream HTTP status code.
- status: u16,
+ status: http::StatusCode,
/// Raw upstream error body.
body: String,
},
diff --git a/crates/protocol/src/stream.rs b/crates/protocol/src/stream.rs
index 550010058..b13b2c50c 100644
--- a/crates/protocol/src/stream.rs
+++ b/crates/protocol/src/stream.rs
@@ -9,6 +9,7 @@ use std::collections::BTreeMap;
use std::pin::Pin;
use futures::{Stream, StreamExt};
+use http::StatusCode;
use serde::{Deserialize, Serialize};
use serde_json::Value;
@@ -21,7 +22,7 @@ use crate::{
/// Status reported for an upstream error delivered inside a streaming body. The
/// upstream already sent a success status line before failing, so there is no real
/// code to propagate; 502 matches how a failed upstream call surfaces elsewhere.
-const MID_STREAM_UPSTREAM_STATUS: u16 = 502;
+const MID_STREAM_UPSTREAM_STATUS: StatusCode = StatusCode::BAD_GATEWAY;
/// A boxed, `Send` stream of response events. Each item may fail independently mid-stream.
pub type LlmResponseStream =
diff --git a/crates/switchyard-server/src/lib.rs b/crates/switchyard-server/src/lib.rs
index fd02cd01b..4e980152f 100644
--- a/crates/switchyard-server/src/lib.rs
+++ b/crates/switchyard-server/src/lib.rs
@@ -913,7 +913,7 @@ fn client_error(error: &LlmClientError) -> Response {
"context_length_exceeded",
),
LlmClientError::UpstreamHttp { status, body } => error_response(
- StatusCode::from_u16(*status).unwrap_or(StatusCode::BAD_GATEWAY),
+ *status,
upstream_error_message(body),
"upstream_error",
"upstream_error",