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
16use alloc::string::String;
17
18/// Error types that can occur when using the Amber API client.
19#[derive(Debug, thiserror::Error)]
20#[non_exhaustive]
21pub enum AmberError {
22    /// HTTP request error.
23    #[cfg(feature = "std")]
24    #[error("HTTP request failed: {0}")]
25    Http(#[from] reqwest::Error),
26
27    /// Rate limit exceeded. Contains the number of seconds to wait.
28    ///
29    /// This error is returned when the API rate limit is hit and automatic
30    /// retries are disabled via `retry_on_rate_limit(false)`.
31    #[error("Rate limit exceeded. Retry after {0} seconds")]
32    RateLimitExceeded(u64),
33
34    /// Rate limit exceeded and max retries exhausted.
35    ///
36    /// This error is returned when the API rate limit is hit and the maximum
37    /// number of retry attempts has been exhausted. The `attempts` field shows
38    /// how many retries were attempted, and `retry_after` shows the suggested
39    /// wait time in seconds before trying again.
40    #[error(
41        "Rate limit exceeded after {attempts} retry attempts. \
42        Last retry-after: {retry_after} seconds"
43    )]
44    RateLimitExhausted {
45        /// Number of retry attempts that were made.
46        attempts: u32,
47        /// Number of seconds to wait before retrying.
48        retry_after: u64,
49    },
50
51    /// Unexpected HTTP status code.
52    ///
53    /// This error is returned when the API returns a non-2xx status code that
54    /// is not specifically handled (e.g., not a rate limit error).
55    #[error("HTTP {status}: {body}")]
56    UnexpectedStatus {
57        /// HTTP status code.
58        status: u16,
59        /// Response body (may be truncated or empty if unreadable).
60        body: String,
61    },
62}
63
64/// Result type for Amber API operations.
65pub type Result<T> = core::result::Result<T, AmberError>;
amber_api/error.rs

amber_api/
error.rs
