@@ -649,6 +649,10 @@ async fn process_sse_with_treatment(
     }
 }
 
+#[cfg(test)]
+#[path = "responses_error_tests.rs"]
+mod error_tests;
+
 #[cfg(test)]
 mod tests {
     use super::*;
 
@@ -1,8 +1,9 @@
-//! Classifies failed Responses events and their rate-limit retry delays.
+//! Classifies failed Responses events and their retry advice.
 //! Only rate-limit codes derive retry delays from plaintext messages.
 
 use crate::error::ApiError;
 use crate::error::parse_flex_unavailable;
+use crate::responses_headers::json_headers_to_http_headers;
 use codex_http_client::RetryAfter;
 use codex_protocol::protocol::MisalignmentErrorDetails;
 use serde::Deserialize;
@@ -23,19 +24,24 @@ struct Error {
 }
 
 pub(super) fn parse_failed_response(response: Option<Value>) -> ApiError {
-    if let Some(error) = response
-        .as_ref()
-        .and_then(|response| response.get("error"))
-        .and_then(parse_flex_unavailable)
-    {
+    let error = response.as_ref().and_then(|response| response.get("error"));
+    let retry_after_header = error
+        .and_then(|error| error.get("headers"))
+        .and_then(Value::as_object)
+        .and_then(|headers| RetryAfter::from_headers(&json_headers_to_http_headers(headers)));
+    if let Some(error) = error.and_then(parse_flex_unavailable) {
         return error;
     }
-    let Some(error) = response
-        .as_ref()
-        .and_then(|response| response.get("error"))
-        .and_then(|error| serde_json::from_value::<Error>(error.clone()).ok())
+    let Some(error) = error.and_then(|error| serde_json::from_value::<Error>(error.clone()).ok())
     else {
-        return ApiError::Stream("response.failed event received".into());
+        let message = "response.failed event received".to_string();
+        return match retry_after_header {
+            Some(_) => ApiError::Retryable {
+                message,
+                retry_after: retry_after_header,
+            },
+            None => ApiError::Stream(message),
+        };
     };
 
     match error.code.as_deref() {
@@ -78,17 +84,20 @@ pub(super) fn parse_failed_response(response: Option<Value>) -> ApiError {
                 .message
                 .unwrap_or_else(|| "Invalid request.".to_string()),
         },
-        Some("server_is_overloaded") => ApiError::ServerOverloaded { retry_after: None },
+        Some("server_is_overloaded") => ApiError::ServerOverloaded {
+            retry_after: retry_after_header,
+        },
         Some("rate_limit_exceeded" | "slow_down") => {
-            let retry_after = try_parse_retry_delay(&error).and_then(RetryAfter::from_delay);
+            let retry_after = retry_after_header
+                .or_else(|| try_parse_retry_delay(&error).and_then(RetryAfter::from_delay));
             ApiError::RateLimitExceeded {
                 message: error.message.unwrap_or_default(),
                 retry_after,
             }
         }
         _ => ApiError::Retryable {
             message: error.message.unwrap_or_default(),
-            retry_after: None,
+            retry_after: retry_after_header,
         },
     }
 }
@@ -106,7 +115,7 @@ fn try_parse_retry_delay(err: &Error) -> Option<Duration> {
             let unit = unit.as_str().to_ascii_lowercase();
 
             if unit == "s" || unit.starts_with("second") {
-                return Some(Duration::from_secs_f64(value));
+                return Duration::try_from_secs_f64(value).ok();
             } else if unit == "ms" {
                 return Some(Duration::from_millis(value as u64));
             }
 
@@ -0,0 +1,156 @@
+//! Regression coverage for retry advice carried by failed Responses events.
+
+use super::process_responses_event;
+use super::spawn_response_stream;
+use crate::api_bridge::map_api_error;
+use crate::common::ResponseEvent;
+use bytes::Bytes;
+use codex_client::StreamResponse;
+use codex_http_client::RetryAfter;
+use codex_protocol::protocol::CodexErrorInfo;
+use futures::StreamExt;
+use futures::stream;
+use http::HeaderMap;
+use http::StatusCode;
+use pretty_assertions::assert_eq;
+use serde_json::json;
+use std::time::Duration;
+
+/// Flex failures remain terminal even with retry headers and a later completed event.
+#[tokio::test(start_paused = true)]
+async fn flex_failure_with_retry_header_ends_stream_immediately() {
+    let error = json!({
+        "code": "flex_unavailable",
+        "plan_type": 42,
+        "headers": {"retry-after": "300"}
+    });
+    for failure in [
+        json!({"type": "error", "error": error}),
+        json!({"type": "response.failed", "response": {"error": error}}),
+    ] {
+        let completed = json!({"type": "response.completed", "response": {"id": "later"}});
+        let bytes = stream::iter([Ok(Bytes::from(format!(
+            "data: {failure}\n\ndata: {completed}\n\n"
+        )))])
+        .chain(stream::pending());
+        let mut stream = spawn_response_stream(
+            StreamResponse {
+                status: StatusCode::OK,
+                headers: HeaderMap::new(),
+                bytes: Box::pin(bytes),
+            },
+            Duration::from_secs(60),
+            /*telemetry*/ None,
+            /*turn_state*/ None,
+        );
+        let error = loop {
+            match stream.next().await {
+                Some(Ok(ResponseEvent::RateLimits(_))) => {}
+                Some(Err(error)) => break map_api_error(error),
+                event => panic!("expected a Flex error, got {event:?}"),
+            }
+        };
+        assert_eq!(
+            (
+                error.to_codex_protocol_error(),
+                error.retry_delay(/*retry_count*/ 1)
+            ),
+            (CodexErrorInfo::FlexUnavailable, None)
+        );
+        assert!(stream.next().await.is_none());
+    }
+}
+
+/// Error headers beat rate-limit message advice; invalid ones fall back.
+#[tokio::test(start_paused = true)]
+async fn rate_limit_plaintext_loses_to_valid_error_header() {
+    for code in ["rate_limit_exceeded", "slow_down"] {
+        for (error_header, expected_seconds) in [
+            (Some("2"), 2),
+            (Some("0"), 0),
+            (Some("Wed, 21 Oct 2015 07:28:00 GMT"), 0),
+            (Some("bad"), 35),
+            (None, 35),
+        ] {
+            let event = serde_json::from_value(json!({
+                "type": "response.failed",
+                "response": {
+                    "error": {
+                        "code": code,
+                        "message": "Try again in 35 seconds.",
+                        "headers": {"Retry-After": error_header}
+                    }
+                }
+            }))
+            .unwrap();
+            let error = map_api_error(process_responses_event(event).unwrap_err().into_api_error());
+            assert_eq!(
+                error.retry_after(),
+                RetryAfter::from_delay(Duration::from_secs(expected_seconds))
+            );
+        }
+    }
+}
+
+/// Retry advice uses the same HTTP value validation as other event headers.
+#[tokio::test(start_paused = true)]
+async fn streamed_retry_after_uses_http_header_validation() {
+    for (error_headers, expected_seconds) in [
+        (json!({"retry-after": "\n5\n"}), 12),
+        (json!({"retry-after": "\t5\t"}), 5),
+        (json!({"Retry-After": "5", "retry-after": "30"}), 30),
+    ] {
+        let event = serde_json::from_value(json!({
+            "type": "response.failed",
+            "response": {"error": {"code": "rate_limit_exceeded", "message": "Try again in 12 seconds.", "headers": error_headers}}
+        }))
+        .unwrap();
+        let error = map_api_error(process_responses_event(event).unwrap_err().into_api_error());
+        assert_eq!(
+            error.retry_after(),
+            RetryAfter::from_delay(Duration::from_secs(expected_seconds))
+        );
+    }
+}
+
+/// Event headers retain their deadlines for overload and generic failures.
+#[tokio::test(start_paused = true)]
+async fn retry_header_survives_other_failed_responses() {
+    for (code, expected_code) in [
+        ("server_is_overloaded", CodexErrorInfo::ServerOverloaded),
+        ("unknown_failure", CodexErrorInfo::Other),
+    ] {
+        let event = serde_json::from_value(json!({
+            "type": "response.failed",
+            "response": {"error": {"code": code, "headers": {"retry-after": "7"}}},
+        }))
+        .unwrap();
+        let error = map_api_error(process_responses_event(event).unwrap_err().into_api_error());
+        assert_eq!(
+            (
+                error.to_codex_protocol_error(),
+                error.retry_after(),
+                error.retry_delay(/*retry_count*/ 1),
+            ),
+            (
+                expected_code,
+                RetryAfter::from_delay(Duration::from_secs(7)),
+                Some(Duration::from_secs(7)),
+            )
+        );
+    }
+}
+
+/// An event header cannot make a quota or policy failure retryable.
+#[tokio::test(start_paused = true)]
+async fn retry_header_does_not_override_terminal_errors() {
+    for code in ["insufficient_quota", "cyber_policy", "bio_policy"] {
+        let event = serde_json::from_value(json!({
+            "type": "response.failed",
+            "response": {"error": {"code": code, "headers": {"retry-after": "1"}}}
+        }))
+        .unwrap();
+        let error = map_api_error(process_responses_event(event).unwrap_err().into_api_error());
+        assert_eq!(error.retry_delay(/*retry_count*/ 1), None, "{code}");
+    }
+}
Original file line number	Diff line number	Diff line change
`@@ -649,6 +649,10 @@ async fn process_sse_with_treatment(`
`649`	`649`	`}`
`650`	`650`	`}`
`651`	`651`
	`652`	`+#[cfg(test)]`
	`653`	`+#[path = "responses_error_tests.rs"]`
	`654`	`+mod error_tests;`
	`655`	`+`
`652`	`656`	`#[cfg(test)]`
`653`	`657`	`mod tests {`
`654`	`658`	`use super::*;`