amber_api/
error.rs

1//! # Error types for the Amber Electric API client
2//!
3//! This module contains all error types and handling for the Amber API client.
4//!
5//! ## Rate Limit Errors
6//!
7//! The client handles rate limits automatically by default, but you may still
8//! encounter rate limit errors if:
9//!
10//! - Automatic retries are disabled via `retry_on_rate_limit(false)`
11//! - The maximum retry attempts are exhausted
12//!
13//! See [`AmberError::RateLimitExceeded`] and [`AmberError::RateLimitExhausted`]
14//! for more details.
15
16/// Error types that can occur when using the Amber API client.
17#[derive(Debug, thiserror::Error)]
18#[non_exhaustive]
19pub enum AmberError {
20    /// HTTP request error.
21    #[error("HTTP request failed: {0}")]
22    Http(#[from] reqwest::Error),
23
24    /// Rate limit exceeded. Contains the number of seconds to wait.
25    ///
26    /// This error is returned when the API rate limit is hit and automatic
27    /// retries are disabled via `retry_on_rate_limit(false)`.
28    #[error("Rate limit exceeded. Retry after {0} seconds")]
29    RateLimitExceeded(u64),
30
31    /// Rate limit exceeded and max retries exhausted.
32    ///
33    /// This error is returned when the API rate limit is hit and the maximum
34    /// number of retry attempts has been exhausted. The `attempts` field shows
35    /// how many retries were attempted, and `retry_after` shows the suggested
36    /// wait time in seconds before trying again.
37    #[error(
38        "Rate limit exceeded after {attempts} retry attempts. \
39        Last retry-after: {retry_after} seconds"
40    )]
41    RateLimitExhausted {
42        /// Number of retry attempts that were made.
43        attempts: u32,
44        /// Number of seconds to wait before retrying.
45        retry_after: u64,
46    },
47
48    /// Unexpected HTTP status code.
49    ///
50    /// This error is returned when the API returns a non-2xx status code that
51    /// is not specifically handled (e.g., not a rate limit error).
52    #[error("HTTP {status}: {body}")]
53    UnexpectedStatus {
54        /// HTTP status code.
55        status: u16,
56        /// Response body (may be truncated or empty if unreadable).
57        body: String,
58    },
59}
60
61/// Result type for Amber API operations.
62pub type Result<T> = core::result::Result<T, AmberError>;
amber_api/error.rs

amber_api/
error.rs
