Document error handling.

README.md

@@ -69,6 +69,12 @@ Ureq supports sending and receiving json, if you enable the "json" feature:
       .into_string()?;
 ```
 
+### Error handling
+
+ureq returns errors via `Result<T, ureq::Error>`. That includes I/O errors,
+protocol errors, and status code errors (when the server responded 4xx or
+5xx). More details on the [Error] type.
+
 ### Features
 
 To enable a minimal dependency tree, some features are off by default.
@@ -189,6 +195,7 @@ If ureq is not what you're looking for, check out these other Rust HTTP clients:
 [post()]: https://docs.rs/ureq/latest/ureq/fn.post.html
 [put()]: https://docs.rs/ureq/latest/ureq/fn.put.html
 [Request]: https://docs.rs/ureq/latest/ureq/struct.Request.html
+[Error]: https://docs.rs/ureq/latest/ureq/enum.Error.html
 [Request::call()]: https://docs.rs/ureq/latest/ureq/struct.Request.html#method.call
 [Request::send()]: https://docs.rs/ureq/latest/ureq/struct.Request.html#method.send
 [Request::send_bytes()]: https://docs.rs/ureq/latest/ureq/struct.Request.html#method.send_bytes

README.tpl

@@ -12,6 +12,7 @@
 [post()]: https://docs.rs/ureq/latest/ureq/fn.post.html
 [put()]: https://docs.rs/ureq/latest/ureq/fn.put.html
 [Request]: https://docs.rs/ureq/latest/ureq/struct.Request.html
+[Error]: https://docs.rs/ureq/latest/ureq/enum.Error.html
 [Request::call()]: https://docs.rs/ureq/latest/ureq/struct.Request.html#method.call
 [Request::send()]: https://docs.rs/ureq/latest/ureq/struct.Request.html#method.send
 [Request::send_bytes()]: https://docs.rs/ureq/latest/ureq/struct.Request.html#method.send_bytes

src/error.rs

@@ -42,6 +42,23 @@ use crate::Response;
 ///     ureq::get(url).call()
 /// }
 /// ```
+///
+/// If you'd like to treat all status code errors as normal, successful responses,
+/// you can use [Result::or_else](std::result::Result::or_else) like this:
+///
+/// ```
+/// use ureq::Error::Status;
+/// # fn main() -> std::result::Result<(), ureq::Error> {
+/// # ureq::is_test(true);
+/// let resp = ureq::get("http://example.com/")
+///   .call()
+///   .or_else(|e| match e { 
+///     Status(_, r) => Ok(r), // turn status errors into Ok Responses.
+///     _ => Err(e),
+///   })?;
+/// # Ok(())
+/// # }
+/// ```
 #[derive(Debug)]
 pub enum Error {
     /// A response was successfully received but had status code >= 400.

src/lib.rs

@@ -82,6 +82,12 @@
 //! # fn main() {}
 //! ```
 //!
+//! ## Error handling
+//!
+//! ureq returns errors via `Result<T, ureq::Error>`. That includes I/O errors,
+//! protocol errors, and status code errors (when the server responded 4xx or
+//! 5xx). More details on the [Error] type.
+//!
 //! ## Features
 //!
 //! To enable a minimal dependency tree, some features are off by default.