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>;