privacy: return distinct status codes instead of a blanket 502

crates/api/src/routes/completions.rs

@@ -6375,38 +6375,47 @@ pub async fn privacy_classify(
                 .unwrap_or_else(|_| StatusCode::INTERNAL_SERVER_ERROR.into_response())
         }
         Err(e) => {
-            let (status_code, error_type, message) = match e {
+            let (status_code, error_type, message, retry_after) = match e {
                 services::completions::ports::CompletionError::RateLimitExceeded(msg) => {
                     tracing::warn!("Concurrent request limit exceeded for privacy classify");
-                    (StatusCode::TOO_MANY_REQUESTS, "rate_limit_error", msg)
+                    (StatusCode::TOO_MANY_REQUESTS, "rate_limit_error", msg, true)
                 }
                 services::completions::ports::CompletionError::ProviderError {
                     status_code,
                     message,
                 } => {
-                    tracing::error!(
-                        upstream_status = status_code,
-                        detail = %message,
-                        "Privacy classify provider error"
-                    );
                     let http_status = StatusCode::from_u16(status_code)
                         .unwrap_or(StatusCode::INTERNAL_SERVER_ERROR);
-                    (
-                        http_status,
-                        "server_error",
-                        "Privacy classify request failed. Please try again later.".to_string(),
-                    )
+                    if http_status.is_client_error() {
+                        tracing::warn!(
+                            upstream_status = status_code,
+                            "Privacy classify provider error"
+                        );
+                        (http_status, "invalid_request_error", message, false)
+                    } else {
+                        tracing::error!(
+                            upstream_status = status_code,
+                            "Privacy classify provider error"
+                        );
+                        (
+                            http_status,
+                            "server_error",
+                            "Privacy classify request failed. Please try again later.".to_string(),
+                            false,
+                        )
+                    }
                 }
                 services::completions::ports::CompletionError::InvalidModel(msg) => {
                     tracing::warn!("Privacy classify model not found");
-                    (StatusCode::NOT_FOUND, "not_found_error", msg)
+                    (StatusCode::NOT_FOUND, "not_found_error", msg, false)
                 }
                 services::completions::ports::CompletionError::ServiceOverloaded(_) => {
                     tracing::warn!("Privacy classify service overloaded");
                     (
                         crate::routes::common::status_overloaded(),
                         "service_overloaded",
                         "All inference backends are overloaded. Please retry with exponential backoff.".to_string(),
+                        true,
                     )
                 }
                 _ => {
@@ -6415,15 +6424,22 @@ pub async fn privacy_classify(
                         StatusCode::INTERNAL_SERVER_ERROR,
                         "server_error",
                         "Privacy classify request failed".to_string(),
+                        false,
                     )
                 }
             };
 
-            (
+            let mut response = (
                 status_code,
                 ResponseJson(ErrorResponse::new(message, error_type.to_string())),
             )
-                .into_response()
+                .into_response();
+            if retry_after {
+                response
+                    .headers_mut()
+                    .insert(header::RETRY_AFTER, header::HeaderValue::from_static("1"));
+            }
+            response
         }
     }
 }
@@ -6677,38 +6693,47 @@ pub async fn privacy_redact(
     {
         Ok(b) => b,
         Err(e) => {
-            let (status_code, error_type, message) = match e {
+            let (status_code, error_type, message, retry_after) = match e {
                 services::completions::ports::CompletionError::RateLimitExceeded(msg) => {
                     tracing::warn!("Concurrent request limit exceeded for privacy redact");
-                    (StatusCode::TOO_MANY_REQUESTS, "rate_limit_error", msg)
+                    (StatusCode::TOO_MANY_REQUESTS, "rate_limit_error", msg, true)
                 }
                 services::completions::ports::CompletionError::ProviderError {
                     status_code,
                     message,
                 } => {
-                    tracing::error!(
-                        upstream_status = status_code,
-                        detail = %message,
-                        "Privacy redact provider error"
-                    );
                     let http_status = StatusCode::from_u16(status_code)
                         .unwrap_or(StatusCode::INTERNAL_SERVER_ERROR);
-                    (
-                        http_status,
-                        "server_error",
-                        "Privacy redact request failed. Please try again later.".to_string(),
-                    )
+                    if http_status.is_client_error() {
+                        tracing::warn!(
+                            upstream_status = status_code,
+                            "Privacy redact provider error"
+                        );
+                        (http_status, "invalid_request_error", message, false)
+                    } else {
+                        tracing::error!(
+                            upstream_status = status_code,
+                            "Privacy redact provider error"
+                        );
+                        (
+                            http_status,
+                            "server_error",
+                            "Privacy redact request failed. Please try again later.".to_string(),
+                            false,
+                        )
+                    }
                 }
                 services::completions::ports::CompletionError::InvalidModel(msg) => {
                     tracing::warn!("Privacy redact model not found");
-                    (StatusCode::NOT_FOUND, "not_found_error", msg)
+                    (StatusCode::NOT_FOUND, "not_found_error", msg, false)
                 }
                 services::completions::ports::CompletionError::ServiceOverloaded(_) => {
                     tracing::warn!("Privacy redact service overloaded");
                     (
                         StatusCode::SERVICE_UNAVAILABLE,
                         "service_overloaded",
                         "The service is temporarily overloaded. Please retry with exponential backoff.".to_string(),
+                        true,
                     )
                 }
                 _ => {
@@ -6717,14 +6742,21 @@ pub async fn privacy_redact(
                         StatusCode::INTERNAL_SERVER_ERROR,
                         "server_error",
                         "Privacy redact request failed".to_string(),
+                        false,
                     )
                 }
             };
-            return (
+            let mut response = (
                 status_code,
                 ResponseJson(ErrorResponse::new(message, error_type.to_string())),
             )
                 .into_response();
+            if retry_after {
+                response
+                    .headers_mut()
+                    .insert(header::RETRY_AFTER, header::HeaderValue::from_static("1"));
+            }
+            return response;
         }
     };
 

crates/api/tests/e2e_all/privacy_classify.rs

@@ -5,6 +5,7 @@
 
 use crate::common::*;
 use api::models::{BatchUpdateModelApiRequest, ErrorResponse};
+use axum::http::header::RETRY_AFTER;
 
 async fn setup_privacy_filter_model(server: &axum_test::TestServer) -> String {
     let mut batch = BatchUpdateModelApiRequest::new();
@@ -243,3 +244,120 @@ async fn test_privacy_classify_costs_deducted() {
         "Privacy classify should bill 10 tokens × 1_000_000 = 10_000_000",
     );
 }
+
+#[tokio::test]
+async fn test_privacy_classify_upstream_429_returns_rate_limit_with_retry_after() {
+    // Given: an upstream privacy provider that rejects the request with a
+    // body containing data that must never leave the provider boundary.
+    const UPSTREAM_BODY_SENTINEL: &str =
+        "UPSTREAM_PRIVACY_BODY_SENTINEL::alice@example.com::123-45-6789";
+    let (server, _pool, mock_provider, _db) = setup_test_server_with_pool().await;
+    setup_privacy_filter_model(&server).await;
+    let org = setup_org_with_credits(&server, 10_000_000_000i64).await;
+    let api_key = get_api_key_for_org(&server, org.id).await;
+    mock_provider
+        .set_privacy_classify_error_override(Some(
+            inference_providers::PrivacyClassifyError::HttpError {
+                status_code: 429,
+                message: UPSTREAM_BODY_SENTINEL.to_string(),
+            },
+        ))
+        .await;
+
+    // When: a client calls the real classify route.
+    let response = server
+        .post("/v1/privacy/classify")
+        .add_header("Authorization", format!("Bearer {api_key}"))
+        .add_header("User-Agent", MOCK_USER_AGENT)
+        .json(&serde_json::json!({
+            "model": "openai/privacy-filter",
+            "input": "Classify this text"
+        }))
+        .await;
+
+    // Then: retry semantics are explicit and the upstream body is absent.
+    assert_eq!(response.status_code(), 429);
+    assert_eq!(
+        response
+            .headers()
+            .get(RETRY_AFTER)
+            .and_then(|value| value.to_str().ok()),
+        Some("1")
+    );
+    let error: ErrorResponse = response.json();
+    assert_eq!(error.error.r#type, "rate_limit_error");
+    assert!(!error.error.message.contains(UPSTREAM_BODY_SENTINEL));
+}
+
+#[tokio::test]
+async fn test_privacy_classify_upstream_413_returns_invalid_request() {
+    // Given: an oversized upstream response whose body contains unsafe data.
+    const UPSTREAM_BODY_SENTINEL: &str =
+        "UPSTREAM_PRIVACY_BODY_SENTINEL::alice@example.com::123-45-6789";
+    let (server, _pool, mock_provider, _db) = setup_test_server_with_pool().await;
+    setup_privacy_filter_model(&server).await;
+    let org = setup_org_with_credits(&server, 10_000_000_000i64).await;
+    let api_key = get_api_key_for_org(&server, org.id).await;
+    mock_provider
+        .set_privacy_classify_error_override(Some(
+            inference_providers::PrivacyClassifyError::HttpError {
+                status_code: 413,
+                message: UPSTREAM_BODY_SENTINEL.to_string(),
+            },
+        ))
+        .await;
+
+    // When: a client calls the real classify route.
+    let response = server
+        .post("/v1/privacy/classify")
+        .add_header("Authorization", format!("Bearer {api_key}"))
+        .add_header("User-Agent", MOCK_USER_AGENT)
+        .json(&serde_json::json!({
+            "model": "openai/privacy-filter",
+            "input": "Classify this text"
+        }))
+        .await;
+
+    // Then: the client receives the status-only invalid-request error.
+    assert_eq!(response.status_code(), 413);
+    let error: ErrorResponse = response.json();
+    assert_eq!(error.error.r#type, "invalid_request_error");
+    assert_eq!(error.error.message, "PII detector returned HTTP 413");
+    assert!(!error.error.message.contains(UPSTREAM_BODY_SENTINEL));
+}
+
+#[tokio::test]
+async fn test_privacy_classify_upstream_500_returns_502_without_upstream_body() {
+    // Given: an upstream server failure whose body contains unsafe data.
+    const UPSTREAM_BODY_SENTINEL: &str =
+        "UPSTREAM_PRIVACY_BODY_SENTINEL::alice@example.com::123-45-6789";
+    let (server, _pool, mock_provider, _db) = setup_test_server_with_pool().await;
+    setup_privacy_filter_model(&server).await;
+    let org = setup_org_with_credits(&server, 10_000_000_000i64).await;
+    let api_key = get_api_key_for_org(&server, org.id).await;
+    mock_provider
+        .set_privacy_classify_error_override(Some(
+            inference_providers::PrivacyClassifyError::HttpError {
+                status_code: 500,
+                message: UPSTREAM_BODY_SENTINEL.to_string(),
+            },
+        ))
+        .await;
+
+    // When: a client calls the real classify route.
+    let response = server
+        .post("/v1/privacy/classify")
+        .add_header("Authorization", format!("Bearer {api_key}"))
+        .add_header("User-Agent", MOCK_USER_AGENT)
+        .json(&serde_json::json!({
+            "model": "openai/privacy-filter",
+            "input": "Classify this text"
+        }))
+        .await;
+
+    // Then: the server failure remains generic and the body stays private.
+    assert_eq!(response.status_code(), 502);
+    let error: ErrorResponse = response.json();
+    assert_eq!(error.error.r#type, "server_error");
+    assert!(!error.error.message.contains(UPSTREAM_BODY_SENTINEL));
+}

crates/api/tests/e2e_all/privacy_redact.rs

@@ -6,6 +6,7 @@
 
 use crate::common::*;
 use api::models::{BatchUpdateModelApiRequest, ErrorResponse};
+use axum::http::header::RETRY_AFTER;
 
 async fn setup_privacy_filter_model(server: &axum_test::TestServer) -> String {
     let mut batch = BatchUpdateModelApiRequest::new();
@@ -377,3 +378,47 @@ async fn test_privacy_redact_costs_deducted() {
         "Privacy redact should bill 10 tokens × 1_000_000 = 10_000_000",
     );
 }
+
+#[tokio::test]
+async fn test_privacy_redact_upstream_429_returns_rate_limit_with_retry_after() {
+    // Given: an upstream privacy provider that rejects the request with a
+    // body containing data that must never leave the provider boundary.
+    const UPSTREAM_BODY_SENTINEL: &str =
+        "UPSTREAM_PRIVACY_BODY_SENTINEL::alice@example.com::123-45-6789";
+    let (server, _pool, mock_provider, _db) = setup_test_server_with_pool().await;
+    setup_privacy_filter_model(&server).await;
+    let org = setup_org_with_credits(&server, 10_000_000_000i64).await;
+    let api_key = get_api_key_for_org(&server, org.id).await;
+    mock_provider
+        .set_privacy_classify_error_override(Some(
+            inference_providers::PrivacyClassifyError::HttpError {
+                status_code: 429,
+                message: UPSTREAM_BODY_SENTINEL.to_string(),
+            },
+        ))
+        .await;
+
+    // When: a client calls the real redact route.
+    let response = server
+        .post("/v1/privacy/redact")
+        .add_header("Authorization", format!("Bearer {api_key}"))
+        .add_header("User-Agent", MOCK_USER_AGENT)
+        .json(&serde_json::json!({
+            "model": "openai/privacy-filter",
+            "input": "Redact this text"
+        }))
+        .await;
+
+    // Then: retry semantics are explicit and the upstream body is absent.
+    assert_eq!(response.status_code(), 429);
+    assert_eq!(
+        response
+            .headers()
+            .get(RETRY_AFTER)
+            .and_then(|value| value.to_str().ok()),
+        Some("1")
+    );
+    let error: ErrorResponse = response.json();
+    assert_eq!(error.error.r#type, "rate_limit_error");
+    assert!(!error.error.message.contains(UPSTREAM_BODY_SENTINEL));
+}