Skip to main content

azure_devops/
error.rs

1use thiserror::Error;
2
3/// Errors that can occur when interacting with Azure DevOps.
4///
5/// All API methods in this crate return `Result<T, AzureDevOpsError>`.
6/// Use `match` or the `?` operator to handle errors.
7///
8/// # Examples
9///
10/// ```ignore
11/// use azure_devops::AzureDevOpsError;
12///
13/// match some_operation().await {
14///     Err(AzureDevOpsError::Auth(msg)) => eprintln!("Auth failed: {msg}"),
15///     Err(AzureDevOpsError::RateLimited { retry_after }) => {
16///         if let Some(seconds) = retry_after {
17///             tokio::time::sleep(std::time::Duration::from_secs(seconds)).await;
18///         }
19///     }
20///     Err(e) => eprintln!("Error: {e}"),
21///     Ok(value) => { /* use value */ }
22/// }
23/// # Ok::<(), AzureDevOpsError>(())
24/// ```
25#[derive(Debug, Error)]
26pub enum AzureDevOpsError {
27    /// A network-level error (DNS, connection refused, TLS, timeout, etc.).
28    ///
29    /// Wraps the underlying [`reqwest::Error`].
30    #[error("network error: {0}")]
31    Network(#[from] reqwest::Error),
32
33    /// Authentication failed (HTTP 401, or invalid credentials provided).
34    ///
35    /// Check that your PAT is valid and has not expired.
36    #[error("authentication failed: {0}")]
37    Auth(String),
38
39    /// The Azure DevOps API returned an error response (HTTP 4xx/5xx).
40    #[error("API error (HTTP {status}): {message}")]
41    Api {
42        /// HTTP status code returned by Azure DevOps.
43        status: u16,
44        /// Human-readable error message from the API response.
45        message: String,
46    },
47
48    /// JSON serialization or deserialization failed.
49    ///
50    /// This typically occurs when the API response format doesn't match
51    /// the expected struct shape. Check for API version mismatches.
52    #[error("serialization error: {0}")]
53    Serialization(#[from] serde_json::Error),
54
55    /// The client was misconfigured (e.g. missing organization URL).
56    ///
57    /// Ensure you call `.organization()` and `.pat()` on the builder
58    /// before calling `.build()`.
59    #[error("invalid configuration: {0}")]
60    Config(String),
61
62    /// The request was rate-limited (HTTP 429).
63    ///
64    /// Azure DevOps enforces rate limits. When this occurs, wait for
65    /// the suggested `retry_after` duration before retrying.
66    #[error("rate limited{}",
67        .retry_after.map_or(String::new(), |s| format!(" (retry after {s}s)")))]
68    RateLimited {
69        /// Suggested wait time in seconds before retrying, if provided
70        /// by the server via the `Retry-After` header.
71        retry_after: Option<u64>,
72    },
73
74    /// A URL could not be parsed.
75    ///
76    /// This usually indicates an invalid organization name or
77    /// malformed API path.
78    #[error("URL error: {0}")]
79    Url(#[from] url::ParseError),
80}
81
82/// Convenience alias for `Result<T, AzureDevOpsError>`.
83pub type Result<T> = std::result::Result<T, AzureDevOpsError>;