HTTP Error cleanup

rspotify-http/Cargo.toml

@@ -14,6 +14,8 @@ keywords = ["spotify", "api"]
 edition = "2018"
 
 [dependencies]
+rspotify-model = { path = "../rspotify-model", version = "0.10.0" }
+
 # Temporary until https://github.com/rust-lang/rfcs/issues/2739, for
 # `maybe_async`.
 async-trait = { version = "0.1.51", optional = true }
@@ -26,6 +28,9 @@ thiserror = "1.0.29"
 reqwest = { version = "0.11.4", default-features = false, features = ["json", "socks"], optional = true }
 ureq = { version = "2.2.0", default-features = false, features = ["json", "cookies"], optional = true }
 
+[dev-dependencies]
+tokio = { version = "1.11.0", features = ["macros", "rt-multi-thread"] }
+
 [features]
 default = ["client-reqwest", "reqwest-default-tls"]
 

rspotify-http/src/reqwest.rs

@@ -10,12 +10,41 @@ use reqwest::{Method, RequestBuilder};
 use serde_json::Value;
 
 /// Custom enum that contains all the possible errors that may occur when using
-/// `reqwest`.
+/// [`reqwest`].
+///
+/// Sample usage:
+///
+/// ```
+/// # #[tokio::main]
+/// # async fn main() {
+/// use rspotify_http::{HttpError, HttpClient, BaseHttpClient};
+///
+/// let client = HttpClient::default();
+/// let response = client.get("wrongurl", None, &Default::default()).await;
+/// match response {
+///     Ok(data) => println!("request succeeded: {:?}", data),
+///     Err(HttpError::Client(e)) => eprintln!("request failed: {}", e),
+///     Err(HttpError::StatusCode(response)) => {
+///         let code = response.status().as_u16();
+///         match response.json::<rspotify_model::ApiError>().await {
+///             Ok(api_error) => eprintln!("status code {}: {:?}", code, api_error),
+///             Err(_) => eprintln!("status code {}", code),
+///         }
+///     },
+/// }
+/// # }
+/// ```
 #[derive(thiserror::Error, Debug)]
 pub enum ReqwestError {
+    /// The request couldn't be completed because there was an error when trying
+    /// to do so
     #[error("request: {0}")]
     Client(#[from] reqwest::Error),
 
+    /// The request was made, but the server returned an unsuccessful status
+    /// code, such as 404 or 503. In some cases, the response may contain a
+    /// custom message from Spotify with more information, which can be
+    /// serialized into [`rspotify_model::ApiError`].
     #[error("status code {}", reqwest::Response::status(.0))]
     StatusCode(reqwest::Response),
 }

rspotify-http/src/ureq.rs

@@ -10,14 +10,42 @@ use ureq::{Request, Response};
 
 /// Custom enum that contains all the possible errors that may occur when using
 /// `ureq`.
+///
+/// Sample usage:
+///
+/// ```
+/// use rspotify_http::{HttpError, HttpClient, BaseHttpClient};
+///
+/// let client = HttpClient::default();
+/// let response = client.get("wrongurl", None, &Default::default());
+/// match response {
+///     Ok(data) => println!("request succeeded: {:?}", data),
+///     Err(HttpError::Transport(e)) => eprintln!("request failed: {}", e),
+///     Err(HttpError::Io(e)) => eprintln!("failed to decode response: {}", e),
+///     Err(HttpError::StatusCode(response)) => {
+///         let code = response.status();
+///         match response.into_json::<rspotify_model::ApiError>() {
+///             Ok(api_error) => eprintln!("status code {}: {:?}", code, api_error),
+///             Err(_) => eprintln!("status code {}", code),
+///         }
+///     },
+/// }
+/// ```
 #[derive(thiserror::Error, Debug)]
 pub enum UreqError {
+    /// The request couldn't be completed because there was an error when trying
+    /// to do so
     #[error("transport: {0}")]
     Transport(#[from] ureq::Transport),
 
+    /// There was an error when trying to decode the response
     #[error("I/O: {0}")]
     Io(#[from] io::Error),
 
+    /// The request was made, but the server returned an unsuccessful status
+    /// code, such as 404 or 503. In some cases, the response may contain a
+    /// custom message from Spotify with more information, which can be
+    /// serialized into [`rspotify_model::ApiError`].
     #[error("status code {}", ureq::Response::status(.0))]
     StatusCode(ureq::Response),
 }