Map reqwest errors to semantically correct Twirp error codes (#314)

* Map reqwest errors to semantically correct Twirp error codes

Replace the blanket From<reqwest::Error> → InvalidArgument mapping with
variant-specific logic:

- is_builder() → InvalidArgument (actually bad input)
- is_redirect() / is_body() / is_decode() → Internal (unexpected behavior)
- everything else (connect, timeout, request) → Unavailable (transient)

This lets downstream consumers distinguish transport failures from
application errors, enabling correct retry decisions.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* Hoist .with_rust_error(e) out of branches

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* Address review feedback on reqwest error mapping tests

- Use localhost TcpListener instead of non-routable IP for timeout test
- Fix misleading comment on builder error test

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

---------

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: tclem

crates/twirp/src/error.rs

@@ -258,10 +258,22 @@ impl From<serde_json::Error> for TwirpErrorResponse {
     }
 }
 
-// unable to build the request
+// Map reqwest errors to semantically appropriate Twirp error codes.
+// Transport failures (connect, timeout) → Unavailable (retryable).
+// Request-building errors → InvalidArgument (caller's fault).
+// Response-parsing errors → Internal (unexpected server behavior).
 impl From<reqwest::Error> for TwirpErrorResponse {
     fn from(e: reqwest::Error) -> Self {
-        invalid_argument(e.to_string()).with_rust_error(e)
+        let msg = e.to_string();
+        let resp = if e.is_builder() {
+            invalid_argument(msg)
+        } else if e.is_redirect() || e.is_body() || e.is_decode() {
+            internal(msg)
+        } else {
+            // connect, timeout, request, and anything else — treat as transient
+            unavailable(msg)
+        };
+        resp.with_rust_error(e)
     }
 }
 
@@ -393,6 +405,42 @@ mod test {
         assert_eq!(response, result);
     }
 
+    #[tokio::test]
+    async fn reqwest_timeout_error_maps_to_unavailable() {
+        // Bind a listener that accepts but never responds, guaranteeing a timeout.
+        let listener = std::net::TcpListener::bind("127.0.0.1:0").unwrap();
+        let addr = listener.local_addr().unwrap();
+        let _accept_thread = std::thread::spawn(move || {
+            let (_stream, _) = listener.accept().unwrap();
+            std::thread::sleep(std::time::Duration::from_secs(60));
+        });
+
+        let client = reqwest::Client::builder()
+            .timeout(std::time::Duration::from_millis(1))
+            .build()
+            .unwrap();
+        let err = client
+            .get(format!("http://{addr}"))
+            .send()
+            .await
+            .unwrap_err();
+        let twirp_err: TwirpErrorResponse = err.into();
+        assert_eq!(twirp_err.code, TwirpErrorCode::Unavailable);
+    }
+
+    #[test]
+    fn reqwest_builder_error_maps_to_invalid_argument() {
+        // An empty URL string triggers a builder error
+        let err = reqwest::Client::builder()
+            .build()
+            .unwrap()
+            .get("")
+            .build()
+            .unwrap_err();
+        let twirp_err: TwirpErrorResponse = err.into();
+        assert_eq!(twirp_err.code, TwirpErrorCode::InvalidArgument);
+    }
+
     #[test]
     fn twirp_error_response_serialization_skips_fields() {
         let response = TwirpErrorResponse {