Preserve provider transport failure diagnostics

Classify reqwest failures before converting them to LLMError, retain
their HTTP status and bounded redacted source chain in metadata, and log
those fields in ACP generation telemetry.

Cover both the shared OpenAI-compatible path and the custom-provider
OpenAIProvider route used by Arli.

Author: leynos

crates/codegen/vtcode-acp/src/zed/agent/handlers.rs

@@ -289,6 +289,24 @@ struct GenerationTelemetry {
     estimated_output_tokens: u64,
 }
 
+#[derive(Debug, Default, PartialEq, Eq)]
+struct ProviderErrorTelemetry<'a> {
+    code: Option<&'a str>,
+    status: Option<u16>,
+    detail: Option<&'a str>,
+}
+
+fn provider_error_telemetry(error: &LLMError) -> ProviderErrorTelemetry<'_> {
+    let LLMError::Network { metadata: Some(metadata), .. } = error else {
+        return ProviderErrorTelemetry::default();
+    };
+    ProviderErrorTelemetry {
+        code: metadata.code.as_deref(),
+        status: metadata.status,
+        detail: metadata.message.as_deref(),
+    }
+}
+
 impl GenerationTelemetry {
     fn start() -> Self {
         Self {
@@ -359,6 +377,7 @@ impl GenerationTelemetry {
         error: &LLMError,
     ) {
         let snapshot = runtime.telemetry_snapshot();
+        let error_telemetry = provider_error_telemetry(error);
         warn!(
             provider = runtime.provider_name(),
             generation_elapsed_ms = duration_millis(self.started_at.elapsed()),
@@ -369,6 +388,9 @@ impl GenerationTelemetry {
             active_provider_permits = snapshot.active_permits,
             permit_limit = ?snapshot.permit_limit,
             circuit_breaker_state = snapshot.circuit_breaker_state,
+            provider_error_code = ?error_telemetry.code,
+            provider_error_status = ?error_telemetry.status,
+            provider_error_detail = ?error_telemetry.detail,
             provider_error = %error,
             "ACP provider generation attempt failed"
         );
@@ -1671,6 +1693,31 @@ mod tests {
 
     use super::*;
 
+    #[test]
+    fn provider_error_telemetry_exposes_structured_network_diagnostics() {
+        let error = LLMError::Network {
+            message: "request failed".to_string(),
+            metadata: Some(LLMErrorMetadata::new(
+                "Arli AI",
+                Some(504),
+                Some("reqwest_timeout_error".to_string()),
+                None,
+                None,
+                None,
+                Some("operation timed out".to_string()),
+            )),
+        };
+
+        assert_eq!(
+            provider_error_telemetry(&error),
+            ProviderErrorTelemetry {
+                code: Some("reqwest_timeout_error"),
+                status: Some(504),
+                detail: Some("operation timed out"),
+            }
+        );
+    }
+
     proptest! {
         #[test]
         fn streaming_eligibility_depends_only_on_provider_support_and_stop_hooks(

crates/codegen/vtcode-llm/src/providers/common.rs

@@ -465,7 +465,7 @@ pub(crate) async fn send_chat_completions(
         .json(payload)
         .send()
         .await
-        .map_err(|error| super::error_handling::format_network_error(provider_name, &error))
+        .map_err(|error| super::error_handling::format_reqwest_network_error(provider_name, &error))
 }
 
 /// Aborts the spawned streaming task when the consumer stream is dropped.

crates/codegen/vtcode-llm/src/providers/error_handling.rs

@@ -8,6 +8,88 @@ use reqwest::Response;
 use serde_json::Value;
 use vtcode_commons::sanitizer::sanitize_provider_diagnostic;
 
+/// Stable classification for failures reported by reqwest.
+///
+/// The value is persisted in [`LLMErrorMetadata::code`] so callers can inspect
+/// the transport failure without parsing reqwest's display text.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub(crate) enum ReqwestErrorKind {
+    Connect,
+    Timeout,
+    Request,
+    Body,
+    Decode,
+    Redirect,
+    Status,
+    Unknown,
+}
+
+impl ReqwestErrorKind {
+    const fn metadata_code(self) -> &'static str {
+        match self {
+            Self::Connect => "reqwest_connect_error",
+            Self::Timeout => "reqwest_timeout_error",
+            Self::Request => "reqwest_request_error",
+            Self::Body => "reqwest_body_error",
+            Self::Decode => "reqwest_decode_error",
+            Self::Redirect => "reqwest_redirect_error",
+            Self::Status => "reqwest_status_error",
+            Self::Unknown => "reqwest_unknown_error",
+        }
+    }
+}
+
+#[derive(Debug, Clone, Copy, Default)]
+struct ReqwestErrorFlags {
+    is_connect: bool,
+    is_timeout: bool,
+    is_request: bool,
+    is_body: bool,
+    is_decode: bool,
+    is_redirect: bool,
+    is_status: bool,
+}
+
+impl From<&reqwest::Error> for ReqwestErrorFlags {
+    fn from(error: &reqwest::Error) -> Self {
+        Self {
+            is_connect: error.is_connect(),
+            is_timeout: error.is_timeout(),
+            is_request: error.is_request(),
+            is_body: error.is_body(),
+            is_decode: error.is_decode(),
+            is_redirect: error.is_redirect(),
+            is_status: error.is_status(),
+        }
+    }
+}
+
+const fn classify_reqwest_flags(flags: ReqwestErrorFlags) -> ReqwestErrorKind {
+    // Some reqwest errors occupy more than one category. Prefer the most
+    // actionable classification over the generic request/body buckets.
+    if flags.is_timeout {
+        ReqwestErrorKind::Timeout
+    } else if flags.is_connect {
+        ReqwestErrorKind::Connect
+    } else if flags.is_decode {
+        ReqwestErrorKind::Decode
+    } else if flags.is_redirect {
+        ReqwestErrorKind::Redirect
+    } else if flags.is_status {
+        ReqwestErrorKind::Status
+    } else if flags.is_body {
+        ReqwestErrorKind::Body
+    } else if flags.is_request {
+        ReqwestErrorKind::Request
+    } else {
+        ReqwestErrorKind::Unknown
+    }
+}
+
+pub(crate) fn classify_reqwest_error(error: &reqwest::Error) -> ReqwestErrorKind {
+    classify_reqwest_flags(error.into())
+}
+
 #[derive(Debug, Clone, Default)]
 struct ApiResponseMetadata {
     request_id: Option<String>,
@@ -111,6 +193,54 @@ pub(crate) fn format_network_error(provider: &str, error: &impl std::fmt::Displa
     LLMError::Network { message: formatted_error, metadata: None }
 }
 
+/// Formats a reqwest transport failure while preserving its structured
+/// classification and source chain in canonical LLM error metadata.
+#[cold]
+pub(crate) fn format_reqwest_network_error(provider: &str, error: &reqwest::Error) -> LLMError {
+    let kind = classify_reqwest_error(error);
+    let formatted_error = error_display::format_llm_error(provider, &format!("network error: {error}"));
+    let source_chain = reqwest_source_chain(error);
+    LLMError::Network {
+        message: formatted_error,
+        metadata: Some(LLMErrorMetadata::new(
+            provider,
+            error.status().map(|status| status.as_u16()),
+            Some(kind.metadata_code().to_owned()),
+            None,
+            None,
+            None,
+            source_chain,
+        )),
+    }
+}
+
+fn reqwest_source_chain(error: &reqwest::Error) -> Option<String> {
+    use std::error::Error as _;
+
+    const MAX_SOURCE_DEPTH: usize = 8;
+
+    let mut current = error.source();
+    let mut depth = 0;
+    let mut diagnostic = String::new();
+    while let Some(source) = current {
+        if !diagnostic.is_empty() {
+            diagnostic.push_str(": ");
+        }
+        diagnostic.push_str(&source.to_string());
+        current = source.source();
+        depth += 1;
+        if depth == MAX_SOURCE_DEPTH {
+            break;
+        }
+    }
+
+    if diagnostic.is_empty() {
+        None
+    } else {
+        Some(sanitize_provider_diagnostic(diagnostic.as_bytes()))
+    }
+}
+
 /// Handle JSON parsing errors with consistent formatting
 #[cold]
 pub(crate) fn format_parse_error(provider: &str, error: &impl std::fmt::Display) -> LLMError {
@@ -333,6 +463,87 @@ fn extract_response_metadata(response: &Response) -> ApiResponseMetadata {
 mod tests {
     use super::*;
 
+    #[test]
+    fn reqwest_error_classification_covers_transport_categories() {
+        let cases = [
+            (ReqwestErrorFlags { is_connect: true, ..Default::default() }, ReqwestErrorKind::Connect),
+            (ReqwestErrorFlags { is_timeout: true, ..Default::default() }, ReqwestErrorKind::Timeout),
+            (ReqwestErrorFlags { is_request: true, ..Default::default() }, ReqwestErrorKind::Request),
+            (ReqwestErrorFlags { is_body: true, ..Default::default() }, ReqwestErrorKind::Body),
+            (ReqwestErrorFlags { is_decode: true, ..Default::default() }, ReqwestErrorKind::Decode),
+            (ReqwestErrorFlags { is_redirect: true, ..Default::default() }, ReqwestErrorKind::Redirect),
+            (ReqwestErrorFlags { is_status: true, ..Default::default() }, ReqwestErrorKind::Status),
+            (ReqwestErrorFlags::default(), ReqwestErrorKind::Unknown),
+        ];
+
+        for (flags, expected) in cases {
+            assert_eq!(classify_reqwest_flags(flags), expected);
+        }
+    }
+
+    #[test]
+    fn reqwest_error_classification_prefers_specific_categories() {
+        let request_timeout = ReqwestErrorFlags {
+            is_timeout: true,
+            is_request: true,
+            ..Default::default()
+        };
+        let request_connect = ReqwestErrorFlags {
+            is_connect: true,
+            is_request: true,
+            ..Default::default()
+        };
+        let body_decode = ReqwestErrorFlags {
+            is_body: true,
+            is_decode: true,
+            ..Default::default()
+        };
+
+        assert_eq!(classify_reqwest_flags(request_timeout), ReqwestErrorKind::Timeout);
+        assert_eq!(classify_reqwest_flags(request_connect), ReqwestErrorKind::Connect);
+        assert_eq!(classify_reqwest_flags(body_decode), ReqwestErrorKind::Decode);
+    }
+
+    #[test]
+    fn reqwest_error_metadata_codes_are_stable() {
+        assert_eq!(ReqwestErrorKind::Connect.metadata_code(), "reqwest_connect_error");
+        assert_eq!(ReqwestErrorKind::Timeout.metadata_code(), "reqwest_timeout_error");
+        assert_eq!(ReqwestErrorKind::Request.metadata_code(), "reqwest_request_error");
+        assert_eq!(ReqwestErrorKind::Body.metadata_code(), "reqwest_body_error");
+        assert_eq!(ReqwestErrorKind::Decode.metadata_code(), "reqwest_decode_error");
+        assert_eq!(ReqwestErrorKind::Redirect.metadata_code(), "reqwest_redirect_error");
+        assert_eq!(ReqwestErrorKind::Status.metadata_code(), "reqwest_status_error");
+        assert_eq!(ReqwestErrorKind::Unknown.metadata_code(), "reqwest_unknown_error");
+    }
+
+    #[tokio::test]
+    async fn reqwest_redirect_error_is_preserved_in_llm_metadata() {
+        use wiremock::{Mock, MockServer, ResponseTemplate, matchers::path};
+
+        let server = MockServer::start().await;
+        Mock::given(path("/loop"))
+            .respond_with(ResponseTemplate::new(302).insert_header("location", format!("{}/loop", server.uri())))
+            .mount(&server)
+            .await;
+        let client = reqwest::Client::builder()
+            .redirect(reqwest::redirect::Policy::limited(1))
+            .build()
+            .expect("redirect-limited test client should build");
+        let error = client
+            .post(format!("{}/loop", server.uri()))
+            .send()
+            .await
+            .expect_err("redirect loop should exceed the configured limit");
+
+        let llm_error = format_reqwest_network_error("Test provider", &error);
+        match llm_error {
+            LLMError::Network { metadata, .. } => {
+                assert_eq!(metadata.as_ref().and_then(|value| value.code.as_deref()), Some("reqwest_redirect_error"));
+            }
+            other => panic!("expected a network error, got {other:?}"),
+        }
+    }
+
     #[test]
     fn test_rate_limit_detection() {
         assert!(is_rate_limit_error(429, ""));

crates/codegen/vtcode-llm/src/providers/openai/provider.rs

@@ -489,12 +489,9 @@ impl OpenAIProvider {
         format!("vtcode-{}", Uuid::new_v4())
     }
 
-    fn format_network_error(&self, error: impl std::fmt::Display) -> provider::LLMError {
+    fn format_network_error(&self, error: &reqwest::Error) -> provider::LLMError {
         let label = self.provider_display_override.as_deref().unwrap_or("OpenAI");
-        provider::LLMError::Network {
-            message: error_display::format_llm_error(label, &format!("Network error: {error}")),
-            metadata: None,
-        }
+        super::super::error_handling::format_reqwest_network_error(label, error)
     }
 
     fn format_auth_error(&self, error: impl std::fmt::Display) -> provider::LLMError {
@@ -572,14 +569,14 @@ impl OpenAIProvider {
         F: Fn(&OpenAIRequestAuth) -> reqwest::RequestBuilder,
     {
         let auth = self.current_request_auth().await?;
-        let response = build_request(&auth).send().await.map_err(|e| self.format_network_error(e))?;
+        let response = build_request(&auth).send().await.map_err(|e| self.format_network_error(&e))?;
 
         if self.uses_refreshable_auth() && Self::auth_retryable_status(response.status()) {
             let retry_auth = self.refresh_request_auth_for_retry().await?;
             return build_request(&retry_auth)
                 .send()
                 .await
-                .map_err(|e| self.format_network_error(e));
+                .map_err(|e| self.format_network_error(&e));
         }
 
         Ok(response)

crates/codegen/vtcode-llm/src/providers/openai/provider/tests.rs

@@ -1077,6 +1077,47 @@ async fn custom_provider_auth_retries_with_refreshed_tokens_after_401() {
     );
 }
 
+#[tokio::test]
+async fn custom_provider_network_error_preserves_display_name_and_reqwest_classification() {
+    let Some(server) = start_mock_server_or_skip().await else {
+        return;
+    };
+    Mock::given(path("/redirect-loop"))
+        .respond_with(ResponseTemplate::new(302).insert_header("location", format!("{}/redirect-loop", server.uri())))
+        .mount(&server)
+        .await;
+    let provider = OpenAIProvider::from_custom_config(
+        "arli".to_string(),
+        "Arli AI".to_string(),
+        Some("test-key".to_string()),
+        Some("test-model".to_string()),
+        None,
+        None,
+        None,
+        None,
+        None,
+        None,
+        None,
+    );
+    let client = reqwest::Client::builder()
+        .redirect(reqwest::redirect::Policy::limited(1))
+        .build()
+        .expect("redirect-limited test client should build");
+
+    let error = provider
+        .send_authorized(|_| client.get(format!("{}/redirect-loop", server.uri())))
+        .await
+        .expect_err("redirect loop should exceed the configured limit");
+
+    match error {
+        provider::LLMError::Network { message, metadata } => {
+            assert!(message.contains("Arli AI"), "custom provider display name missing: {message}");
+            assert_eq!(metadata.as_ref().and_then(|value| value.code.as_deref()), Some("reqwest_redirect_error"));
+        }
+        other => panic!("expected a network error, got {other:?}"),
+    }
+}
+
 fn chat_completion_response_body(text: &str) -> Value {
     json!({
         "id": "chatcmpl-test",