ferric_fred/error.rs
1use std::time::Duration;
2
3/// Errors returned by the `ferric-fred` client.
4///
5/// The library never panics on a network or parse failure — those surface here
6/// as `Err`. The enum is `#[non_exhaustive]` so new variants can be added
7/// without a breaking change (see ADR-0004).
8#[derive(Debug, thiserror::Error)]
9#[non_exhaustive]
10pub enum Error {
11 /// A connection, timeout, or TLS-level failure from the HTTP transport.
12 #[error("HTTP transport error")]
13 Transport(#[from] reqwest::Error),
14
15 /// FRED returned an error payload. FRED encodes errors in the response body
16 /// with a code and message alongside the HTTP status.
17 #[error("FRED API error (HTTP {status}): {message}")]
18 Api {
19 /// HTTP status code of the response.
20 status: u16,
21 /// FRED's own error code, when present in the body.
22 code: Option<u32>,
23 /// Human-readable error message.
24 message: String,
25 },
26
27 /// A response body did not match the expected shape.
28 #[error("failed to deserialize FRED response")]
29 Deserialize(#[from] serde_json::Error),
30
31 /// Caller-side validation failed before any request was made.
32 #[error("invalid input: {0}")]
33 InvalidInput(String),
34
35 /// FRED rate-limited the request. Surfaced distinctly so callers can back
36 /// off.
37 #[error("rate limited by FRED")]
38 RateLimited {
39 /// Suggested delay before retrying, if FRED provided one.
40 retry_after: Option<Duration>,
41 },
42}