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

feat(runner): expose safe route failure summaries (#537)

Bryan Bednarski1b677156c682
diff --git a/Cargo.lock b/Cargo.lock
index 945c6d5f0..c3029243f 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -2363,6 +2363,7 @@ dependencies = [
"reqwest",
"serde",
"serde_json",
+ "strum_macros",
"switchyard-libsy",
"switchyard-llm-client",
"switchyard-protocol",
diff --git a/Cargo.toml b/Cargo.toml
index 770043465..4a46fe6ff 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -45,6 +45,7 @@ switchyard-protocol = { path = "crates/protocol", version = "0.2.0" }
switchyard-runner = { path = "crates/switchyard-runner", version = "0.2.0" }
switchyard-server = { path = "crates/switchyard-server", version = "0.2.0" }
switchyard-translation = { path = "crates/switchyard-translation", version = "0.2.0" }
+strum_macros = "0.28"
thiserror = "2"
tokio = { version = "1", features = ["full"] }
tracing = { version = "0.1", default-features = false, features = ["attributes", "std"] }
diff --git a/crates/switchyard-runner/Cargo.toml b/crates/switchyard-runner/Cargo.toml
index 5545f2c19..5da89fb60 100644
--- a/crates/switchyard-runner/Cargo.toml
+++ b/crates/switchyard-runner/Cargo.toml
@@ -20,6 +20,7 @@ serde.workspace = true
serde_json.workspace = true
switchyard-llm-client.workspace = true
switchyard-protocol.workspace = true
+strum_macros.workspace = true
thiserror.workspace = true
toml = "1.1"
tracing.workspace = true
diff --git a/crates/switchyard-runner/src/failure.rs b/crates/switchyard-runner/src/failure.rs
new file mode 100644
index 000000000..4e2901b7a
--- /dev/null
+++ b/crates/switchyard-runner/src/failure.rs
@@ -0,0 +1,338 @@
+// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+//! Safe, structured summaries of route-execution failures for telemetry.
+
+use libsy::LibsyError;
+use strum_macros::IntoStaticStr;
+use switchyard_protocol::{LlmClientError, ModelId};
+
+use crate::RunnerError;
+
+/// Stable class of a terminal route-execution failure.
+///
+/// This deliberately carries no provider message, response body, or source
+/// error. It is suitable for logs and telemetry, not client-facing rendering.
+#[non_exhaustive]
+#[derive(Clone, Copy, Debug, IntoStaticStr)]
+#[strum(serialize_all = "snake_case")]
+pub enum RouteErrorKind {
+ /// The upstream returned a non-success HTTP response.
+ UpstreamHttp,
+ /// The selected target rejected the request because its context window was exceeded.
+ ContextWindowExceeded,
+ /// The upstream request timed out.
+ Timeout,
+ /// The upstream could not be reached or the request could not be sent.
+ Transport,
+ /// The upstream response could not be decoded or validated.
+ InvalidResponse,
+ /// Decoding the inbound request failed in translation.
+ RequestTranslation,
+ /// Encoding the request for the upstream failed in translation.
+ RequestEncoding,
+ /// Decoding or encoding the response failed in translation.
+ ResponseTranslation,
+ /// The request cannot be served as supplied.
+ InvalidRequest,
+ /// The configured route or client cannot serve the request.
+ Configuration,
+ /// The routing algorithm or driver could not produce an outcome.
+ Algorithm,
+ /// A failure without a safe, more specific kind.
+ Other,
+}
+
+impl RouteErrorKind {
+ /// Returns the stable telemetry value for this kind.
+ pub fn as_str(self) -> &'static str {
+ self.into()
+ }
+}
+
+/// When a terminal failure occurred relative to response delivery.
+#[non_exhaustive]
+#[derive(Clone, Copy, Debug, IntoStaticStr)]
+#[strum(serialize_all = "snake_case")]
+pub enum RouteErrorPhase {
+ /// The route failed before returning a response to its caller.
+ BeforeResponse,
+ /// A previously returned streaming response failed while it was consumed.
+ DuringStream,
+}
+
+impl RouteErrorPhase {
+ /// Returns the stable telemetry value for this phase.
+ pub fn as_str(self) -> &'static str {
+ self.into()
+ }
+}
+
+/// Safe, structured terminal-failure data for routing telemetry.
+#[non_exhaustive]
+#[derive(Clone, Debug)]
+pub struct RouteErrorSummary {
+ /// Stable failure classification.
+ pub kind: RouteErrorKind,
+ /// Whether the error preceded response delivery or occurred while streaming.
+ pub phase: RouteErrorPhase,
+ /// Upstream HTTP status, when directly available.
+ pub upstream_status: Option<u16>,
+ /// Selected target that failed, when the runner knows it.
+ pub target: Option<ModelId>,
+}
+
+impl RunnerError {
+ /// Returns a safe telemetry summary for a failure before response delivery.
+ pub fn execution_error_summary(&self) -> RouteErrorSummary {
+ match self {
+ Self::Algorithm(LibsyError::ClientCall { target, source }) => {
+ client_error_summary(source, RouteErrorPhase::BeforeResponse, Some(target))
+ }
+ Self::Client(source) => {
+ client_error_summary(source, RouteErrorPhase::BeforeResponse, None)
+ }
+ Self::Configuration { .. } => summary(
+ RouteErrorKind::Configuration,
+ RouteErrorPhase::BeforeResponse,
+ None,
+ None,
+ ),
+ Self::UnknownRouteModel(_)
+ | Self::IncompatibleCallerFormat(_)
+ | Self::CountTokensUnsupported => summary(
+ RouteErrorKind::InvalidRequest,
+ RouteErrorPhase::BeforeResponse,
+ None,
+ None,
+ ),
+ Self::Algorithm(_) => summary(
+ RouteErrorKind::Algorithm,
+ RouteErrorPhase::BeforeResponse,
+ None,
+ None,
+ ),
+ }
+ }
+}
+
+/// Returns a safe telemetry summary for an error yielded by an active response stream.
+///
+/// `served_model` should be the target recorded on the response before its stream was returned.
+pub fn stream_error_summary(
+ error: &LlmClientError,
+ served_model: Option<&ModelId>,
+) -> RouteErrorSummary {
+ client_error_summary(error, RouteErrorPhase::DuringStream, served_model)
+}
+
+fn client_error_summary(
+ error: &LlmClientError,
+ phase: RouteErrorPhase,
+ target: Option<&ModelId>,
+) -> RouteErrorSummary {
+ let target = target.or(match error {
+ // Context-window errors carry the resolved target model when a caller has not
+ // already supplied the route's selected or served target.
+ LlmClientError::ContextWindowExceeded { model, .. } => Some(model),
+ _ => None,
+ });
+ let (kind, upstream_status) = match error {
+ LlmClientError::UpstreamHttp { status, .. } => {
+ (RouteErrorKind::UpstreamHttp, Some(status.as_u16()))
+ }
+ LlmClientError::ContextWindowExceeded { .. } => {
+ (RouteErrorKind::ContextWindowExceeded, None)
+ }
+ LlmClientError::Timeout { .. } => (RouteErrorKind::Timeout, None),
+ LlmClientError::Transport { .. } => (RouteErrorKind::Transport, None),
+ LlmClientError::InvalidResponse { .. } => (RouteErrorKind::InvalidResponse, None),
+ LlmClientError::RequestTranslation(_) => (RouteErrorKind::RequestTranslation, None),
+ LlmClientError::RequestEncoding(_) => (RouteErrorKind::RequestEncoding, None),
+ LlmClientError::ResponseTranslation(_) => (RouteErrorKind::ResponseTranslation, None),
+ LlmClientError::InvalidRequest { .. } => (RouteErrorKind::InvalidRequest, None),
+ LlmClientError::Configuration { .. } => (RouteErrorKind::Configuration, None),
+ LlmClientError::Ffi { .. } | LlmClientError::General(_) => (RouteErrorKind::Other, None),
+ _ => (RouteErrorKind::Other, None),
+ };
+ summary(kind, phase, upstream_status, target)
+}
+
+fn summary(
+ kind: RouteErrorKind,
+ phase: RouteErrorPhase,
+ upstream_status: Option<u16>,
+ target: Option<&ModelId>,
+) -> RouteErrorSummary {
+ RouteErrorSummary {
+ kind,
+ phase,
+ upstream_status,
+ target: target.cloned(),
+ }
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+
+ const SECRET: &str = "patient name is Jane Doe";
+
+ #[test]
+ fn execution_error_summary_keeps_http_status_and_target_without_body() {
+ let error = RunnerError::Algorithm(LibsyError::ClientCall {
+ target: ModelId::from("strong"),
+ source: LlmClientError::UpstreamHttp {
+ status: reqwest::StatusCode::SERVICE_UNAVAILABLE,
+ body: format!("upstream response: {SECRET}"),
+ },
+ });
+
+ let summary = error.execution_error_summary();
+
+ assert!(matches!(summary.kind, RouteErrorKind::UpstreamHttp));
+ assert!(matches!(summary.phase, RouteErrorPhase::BeforeResponse));
+ assert_eq!(summary.upstream_status, Some(503));
+ assert_eq!(summary.target.as_ref().map(ModelId::as_str), Some("strong"));
+ assert!(!format!("{summary:?}").contains(SECRET));
+ }
+
+ #[test]
+ fn execution_error_summary_reduces_untrusted_messages_to_kinds() {
+ let error = RunnerError::Algorithm(LibsyError::AlgorithmError {
+ message: SECRET.to_string(),
+ });
+
+ let summary = error.execution_error_summary();
+
+ assert!(matches!(summary.kind, RouteErrorKind::Algorithm));
+ assert_eq!(summary.target, None);
+ assert!(!format!("{summary:?}").contains(SECRET));
+ }
+
+ #[test]
+ fn stream_error_summary_preserves_served_target_without_source_text() {
+ let error = LlmClientError::Timeout {
+ source: std::io::Error::other(SECRET).into(),
+ };
+
+ let summary = stream_error_summary(&error, Some(&ModelId::from("fallback")));
+
+ assert!(matches!(summary.kind, RouteErrorKind::Timeout));
+ assert!(matches!(summary.phase, RouteErrorPhase::DuringStream));
+ assert_eq!(
+ summary.target.as_ref().map(ModelId::as_str),
+ Some("fallback")
+ );
+ assert!(!format!("{summary:?}").contains(SECRET));
+ }
+
+ #[test]
+ fn stream_error_summary_uses_context_window_model_without_a_served_target() {
+ let error = LlmClientError::ContextWindowExceeded {
+ model: ModelId::from("weak"),
+ message: SECRET.to_string(),
+ };
+
+ let summary = stream_error_summary(&error, None);
+
+ assert!(matches!(
+ summary.kind,
+ RouteErrorKind::ContextWindowExceeded
+ ));
+ assert!(matches!(summary.phase, RouteErrorPhase::DuringStream));
+ assert_eq!(summary.target.as_ref().map(ModelId::as_str), Some("weak"));
+ assert!(!format!("{summary:?}").contains(SECRET));
+ }
+
+ #[test]
+ fn client_error_kinds_have_stable_telemetry_values() {
+ let cases = vec![
+ (
+ LlmClientError::ContextWindowExceeded {
+ model: ModelId::from("weak"),
+ message: SECRET.to_string(),
+ },
+ "context_window_exceeded",
+ ),
+ (
+ LlmClientError::Transport {
+ source: std::io::Error::other(SECRET).into(),
+ },
+ "transport",
+ ),
+ (
+ LlmClientError::InvalidResponse {
+ source: std::io::Error::other(SECRET).into(),
+ },
+ "invalid_response",
+ ),
+ (
+ LlmClientError::RequestTranslation(SECRET.to_string()),
+ "request_translation",
+ ),
+ (
+ LlmClientError::RequestEncoding(SECRET.to_string()),
+ "request_encoding",
+ ),
+ (
+ LlmClientError::ResponseTranslation(SECRET.to_string()),
+ "response_translation",
+ ),
+ (
+ LlmClientError::Configuration {
+ message: SECRET.to_string(),
+ },
+ "configuration",
+ ),
+ (
+ LlmClientError::InvalidRequest {
+ message: SECRET.to_string(),
+ },
+ "invalid_request",
+ ),
+ (LlmClientError::General(SECRET.to_string()), "other"),
+ ];
+
+ for (error, value) in cases {
+ let summary = stream_error_summary(&error, None);
+ assert_eq!(summary.kind.as_str(), value);
+ assert!(!format!("{summary:?}").contains(SECRET));
+ }
+ }
+
+ #[test]
+ fn route_error_phases_have_stable_telemetry_values() {
+ assert_eq!(RouteErrorPhase::BeforeResponse.as_str(), "before_response");
+ assert_eq!(RouteErrorPhase::DuringStream.as_str(), "during_stream");
+ }
+
+ #[test]
+ fn direct_client_errors_do_not_claim_a_target() {
+ let error = RunnerError::Client(LlmClientError::Timeout {
+ source: std::io::Error::other(SECRET).into(),
+ });
+
+ let summary = error.execution_error_summary();
+
+ assert!(matches!(summary.kind, RouteErrorKind::Timeout));
+ assert!(matches!(summary.phase, RouteErrorPhase::BeforeResponse));
+ assert_eq!(summary.target, None);
+ assert!(!format!("{summary:?}").contains(SECRET));
+ }
+
+ #[test]
+ fn runner_request_and_configuration_errors_are_classified() {
+ let configuration = RunnerError::configuration(SECRET);
+ assert!(matches!(
+ configuration.execution_error_summary().kind,
+ RouteErrorKind::Configuration
+ ));
+
+ let unsupported = RunnerError::CountTokensUnsupported;
+ assert!(matches!(
+ unsupported.execution_error_summary().kind,
+ RouteErrorKind::InvalidRequest
+ ));
+ }
+}
diff --git a/crates/switchyard-runner/src/lib.rs b/crates/switchyard-runner/src/lib.rs
index d69f2da01..75543c2fe 100644
--- a/crates/switchyard-runner/src/lib.rs
+++ b/crates/switchyard-runner/src/lib.rs
@@ -5,6 +5,7 @@
mod algorithm;
mod config;
+mod failure;
mod route;
mod runner;
@@ -12,6 +13,7 @@ pub use algorithm::{
AdvisorTriggerConfig, AlgorithmConfigError, AlgorithmSpec, ClassifierMode,
ClassifierPolicyConfig, LlmClassifierRouteConfig, StageClassifierConfig, SubagentRouteConfig,
};
+pub use failure::{RouteErrorKind, RouteErrorPhase, RouteErrorSummary, stream_error_summary};
pub use route::{
CallerAuthKind, CountTokensTarget, ModelCapabilities, Route, RunOutput, RunnerError,
};