reqwest/
error.rs

1#![cfg_attr(target_arch = "wasm32", allow(unused))]
2use std::error::Error as StdError;
3use std::fmt;
4use std::io;
5
6use crate::{StatusCode, Url};
7
8/// A `Result` alias where the `Err` case is `reqwest::Error`.
9pub type Result<T> = std::result::Result<T, Error>;
10
11/// The Errors that may occur when processing a `Request`.
12///
13/// Note: Errors may include the full URL used to make the `Request`. If the URL
14/// contains sensitive information (e.g. an API key as a query parameter), be
15/// sure to remove it ([`without_url`](Error::without_url))
16pub struct Error {
17    inner: Box<Inner>,
18}
19
20pub(crate) type BoxError = Box<dyn StdError + Send + Sync>;
21
22struct Inner {
23    kind: Kind,
24    source: Option<BoxError>,
25    url: Option<Url>,
26}
27
28impl Error {
29    pub(crate) fn new<E>(kind: Kind, source: Option<E>) -> Error
30    where
31        E: Into<BoxError>,
32    {
33        Error {
34            inner: Box::new(Inner {
35                kind,
36                source: source.map(Into::into),
37                url: None,
38            }),
39        }
40    }
41
42    /// Returns a possible URL related to this error.
43    ///
44    /// # Examples
45    ///
46    /// ```
47    /// # async fn run() {
48    /// // displays last stop of a redirect loop
49    /// let response = reqwest::get("http://site.with.redirect.loop").await;
50    /// if let Err(e) = response {
51    ///     if e.is_redirect() {
52    ///         if let Some(final_stop) = e.url() {
53    ///             println!("redirect loop at {final_stop}");
54    ///         }
55    ///     }
56    /// }
57    /// # }
58    /// ```
59    pub fn url(&self) -> Option<&Url> {
60        self.inner.url.as_ref()
61    }
62
63    /// Returns a mutable reference to the URL related to this error
64    ///
65    /// This is useful if you need to remove sensitive information from the URL
66    /// (e.g. an API key in the query), but do not want to remove the URL
67    /// entirely.
68    pub fn url_mut(&mut self) -> Option<&mut Url> {
69        self.inner.url.as_mut()
70    }
71
72    /// Add a url related to this error (overwriting any existing)
73    pub fn with_url(mut self, url: Url) -> Self {
74        self.inner.url = Some(url);
75        self
76    }
77
78    /// Strip the related url from this error (if, for example, it contains
79    /// sensitive information)
80    pub fn without_url(mut self) -> Self {
81        self.inner.url = None;
82        self
83    }
84
85    /// Returns true if the error is from a type Builder.
86    pub fn is_builder(&self) -> bool {
87        matches!(self.inner.kind, Kind::Builder)
88    }
89
90    /// Returns true if the error is from a `RedirectPolicy`.
91    pub fn is_redirect(&self) -> bool {
92        matches!(self.inner.kind, Kind::Redirect)
93    }
94
95    /// Returns true if the error is from `Response::error_for_status`.
96    pub fn is_status(&self) -> bool {
97        matches!(self.inner.kind, Kind::Status(_))
98    }
99
100    /// Returns true if the error is related to a timeout.
101    pub fn is_timeout(&self) -> bool {
102        let mut source = self.source();
103
104        while let Some(err) = source {
105            if err.is::<TimedOut>() {
106                return true;
107            }
108            if let Some(io) = err.downcast_ref::<io::Error>() {
109                if io.kind() == io::ErrorKind::TimedOut {
110                    return true;
111                }
112            }
113            source = err.source();
114        }
115
116        false
117    }
118
119    /// Returns true if the error is related to the request
120    pub fn is_request(&self) -> bool {
121        matches!(self.inner.kind, Kind::Request)
122    }
123
124    #[cfg(not(target_arch = "wasm32"))]
125    /// Returns true if the error is related to connect
126    pub fn is_connect(&self) -> bool {
127        let mut source = self.source();
128
129        while let Some(err) = source {
130            if let Some(hyper_err) = err.downcast_ref::<hyper_util::client::legacy::Error>() {
131                if hyper_err.is_connect() {
132                    return true;
133                }
134            }
135
136            source = err.source();
137        }
138
139        false
140    }
141
142    /// Returns true if the error is related to the request or response body
143    pub fn is_body(&self) -> bool {
144        matches!(self.inner.kind, Kind::Body)
145    }
146
147    /// Returns true if the error is related to decoding the response's body
148    pub fn is_decode(&self) -> bool {
149        matches!(self.inner.kind, Kind::Decode)
150    }
151
152    /// Returns the status code, if the error was generated from a response.
153    pub fn status(&self) -> Option<StatusCode> {
154        match self.inner.kind {
155            Kind::Status(code) => Some(code),
156            _ => None,
157        }
158    }
159
160    // private
161
162    #[allow(unused)]
163    pub(crate) fn into_io(self) -> io::Error {
164        io::Error::new(io::ErrorKind::Other, self)
165    }
166}
167
168impl fmt::Debug for Error {
169    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
170        let mut builder = f.debug_struct("reqwest::Error");
171
172        builder.field("kind", &self.inner.kind);
173
174        if let Some(ref url) = self.inner.url {
175            builder.field("url", &url.as_str());
176        }
177        if let Some(ref source) = self.inner.source {
178            builder.field("source", source);
179        }
180
181        builder.finish()
182    }
183}
184
185impl fmt::Display for Error {
186    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
187        match self.inner.kind {
188            Kind::Builder => f.write_str("builder error")?,
189            Kind::Request => f.write_str("error sending request")?,
190            Kind::Body => f.write_str("request or response body error")?,
191            Kind::Decode => f.write_str("error decoding response body")?,
192            Kind::Redirect => f.write_str("error following redirect")?,
193            Kind::Upgrade => f.write_str("error upgrading connection")?,
194            Kind::Status(ref code) => {
195                let prefix = if code.is_client_error() {
196                    "HTTP status client error"
197                } else {
198                    debug_assert!(code.is_server_error());
199                    "HTTP status server error"
200                };
201                write!(f, "{prefix} ({code})")?;
202            }
203        };
204
205        if let Some(url) = &self.inner.url {
206            write!(f, " for url ({url})")?;
207        }
208
209        Ok(())
210    }
211}
212
213impl StdError for Error {
214    fn source(&self) -> Option<&(dyn StdError + 'static)> {
215        self.inner.source.as_ref().map(|e| &**e as _)
216    }
217}
218
219#[cfg(target_arch = "wasm32")]
220impl From<crate::error::Error> for wasm_bindgen::JsValue {
221    fn from(err: Error) -> wasm_bindgen::JsValue {
222        js_sys::Error::from(err).into()
223    }
224}
225
226#[cfg(target_arch = "wasm32")]
227impl From<crate::error::Error> for js_sys::Error {
228    fn from(err: Error) -> js_sys::Error {
229        js_sys::Error::new(&format!("{err}"))
230    }
231}
232
233#[derive(Debug)]
234pub(crate) enum Kind {
235    Builder,
236    Request,
237    Redirect,
238    Status(StatusCode),
239    Body,
240    Decode,
241    Upgrade,
242}
243
244// constructors
245
246pub(crate) fn builder<E: Into<BoxError>>(e: E) -> Error {
247    Error::new(Kind::Builder, Some(e))
248}
249
250pub(crate) fn body<E: Into<BoxError>>(e: E) -> Error {
251    Error::new(Kind::Body, Some(e))
252}
253
254pub(crate) fn decode<E: Into<BoxError>>(e: E) -> Error {
255    Error::new(Kind::Decode, Some(e))
256}
257
258pub(crate) fn request<E: Into<BoxError>>(e: E) -> Error {
259    Error::new(Kind::Request, Some(e))
260}
261
262pub(crate) fn redirect<E: Into<BoxError>>(e: E, url: Url) -> Error {
263    Error::new(Kind::Redirect, Some(e)).with_url(url)
264}
265
266pub(crate) fn status_code(url: Url, status: StatusCode) -> Error {
267    Error::new(Kind::Status(status), None::<Error>).with_url(url)
268}
269
270pub(crate) fn url_bad_scheme(url: Url) -> Error {
271    Error::new(Kind::Builder, Some(BadScheme)).with_url(url)
272}
273
274pub(crate) fn url_invalid_uri(url: Url) -> Error {
275    Error::new(Kind::Builder, Some("Parsed Url is not a valid Uri")).with_url(url)
276}
277
278if_wasm! {
279    pub(crate) fn wasm(js_val: wasm_bindgen::JsValue) -> BoxError {
280        format!("{js_val:?}").into()
281    }
282}
283
284pub(crate) fn upgrade<E: Into<BoxError>>(e: E) -> Error {
285    Error::new(Kind::Upgrade, Some(e))
286}
287
288// io::Error helpers
289
290#[cfg(any(
291    feature = "gzip",
292    feature = "zstd",
293    feature = "brotli",
294    feature = "deflate",
295    feature = "blocking",
296))]
297pub(crate) fn into_io(e: BoxError) -> io::Error {
298    io::Error::new(io::ErrorKind::Other, e)
299}
300
301#[allow(unused)]
302pub(crate) fn decode_io(e: io::Error) -> Error {
303    if e.get_ref().map(|r| r.is::<Error>()).unwrap_or(false) {
304        *e.into_inner()
305            .expect("io::Error::get_ref was Some(_)")
306            .downcast::<Error>()
307            .expect("StdError::is() was true")
308    } else {
309        decode(e)
310    }
311}
312
313// internal Error "sources"
314
315#[derive(Debug)]
316pub(crate) struct TimedOut;
317
318impl fmt::Display for TimedOut {
319    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
320        f.write_str("operation timed out")
321    }
322}
323
324impl StdError for TimedOut {}
325
326#[derive(Debug)]
327pub(crate) struct BadScheme;
328
329impl fmt::Display for BadScheme {
330    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
331        f.write_str("URL scheme is not allowed")
332    }
333}
334
335impl StdError for BadScheme {}
336
337#[cfg(test)]
338mod tests {
339    use super::*;
340
341    fn assert_send<T: Send>() {}
342    fn assert_sync<T: Sync>() {}
343
344    #[test]
345    fn test_source_chain() {
346        let root = Error::new(Kind::Request, None::<Error>);
347        assert!(root.source().is_none());
348
349        let link = super::body(root);
350        assert!(link.source().is_some());
351        assert_send::<Error>();
352        assert_sync::<Error>();
353    }
354
355    #[test]
356    fn mem_size_of() {
357        use std::mem::size_of;
358        assert_eq!(size_of::<Error>(), size_of::<usize>());
359    }
360
361    #[test]
362    fn roundtrip_io_error() {
363        let orig = super::request("orig");
364        // Convert reqwest::Error into an io::Error...
365        let io = orig.into_io();
366        // Convert that io::Error back into a reqwest::Error...
367        let err = super::decode_io(io);
368        // It should have pulled out the original, not nested it...
369        match err.inner.kind {
370            Kind::Request => (),
371            _ => panic!("{err:?}"),
372        }
373    }
374
375    #[test]
376    fn from_unknown_io_error() {
377        let orig = io::Error::new(io::ErrorKind::Other, "orly");
378        let err = super::decode_io(orig);
379        match err.inner.kind {
380            Kind::Decode => (),
381            _ => panic!("{err:?}"),
382        }
383    }
384
385    #[test]
386    fn is_timeout() {
387        let err = super::request(super::TimedOut);
388        assert!(err.is_timeout());
389
390        let io = io::Error::new(io::ErrorKind::Other, err);
391        let nested = super::request(io);
392        assert!(nested.is_timeout());
393    }
394}
reqwest/error.rs

reqwest/
error.rs
