rusty_fmp/
error.rs

1//! Error types for the FMP CLI.
2
3use std::process::ExitCode;
4
5/// Convenient result alias for this crate.
6pub type Result<T> = std::result::Result<T, Error>;
7
8/// Errors returned by the FMP CLI and client.
9#[derive(Debug, thiserror::Error)]
10#[non_exhaustive]
11pub enum Error {
12    /// The API key was not provided.
13    #[error("missing FMP API key; set FMP_API_KEY or pass --api-key")]
14    MissingApiKey,
15
16    /// The configured base URL is invalid.
17    #[error("invalid FMP base URL: {0}")]
18    InvalidBaseUrl(String),
19
20    /// A required CLI argument was not provided.
21    #[error("missing required CLI argument: {0}")]
22    MissingArgument(&'static str),
23
24    /// The API returned a non-successful response.
25    #[error("FMP API request failed with HTTP {status}: {message}")]
26    Api {
27        /// HTTP status code returned by the API.
28        status: u16,
29        /// Redacted response body or status message.
30        message: String,
31    },
32
33    /// The API rate-limited the request.
34    #[error("FMP API request was rate limited with HTTP {status}: {message}")]
35    RateLimited {
36        /// HTTP status code returned by the API.
37        status: u16,
38        /// Redacted response body or status message.
39        message: String,
40    },
41
42    /// A strict symbol lookup returned no data.
43    #[error(
44        "empty result for symbol {symbol} from {endpoint}; try `fmp-agent search {search_query}` to verify the symbol, or rerun without --strict-empty to keep the raw FMP response"
45    )]
46    EmptyResult {
47        /// Symbol or symbol list used for the lookup.
48        symbol: String,
49        /// Query suggested for discovery with `fmp-agent search`.
50        search_query: String,
51        /// API endpoint path that returned the empty payload.
52        endpoint: &'static str,
53    },
54
55    /// A CLI command maps to an endpoint that FMP no longer documents for the stable API.
56    #[error("endpoint {endpoint} is unavailable: {message}")]
57    EndpointUnavailable {
58        /// Endpoint path or command identifier that is unavailable.
59        endpoint: &'static str,
60        /// User-facing explanation of the unavailable endpoint.
61        message: &'static str,
62    },
63
64    /// The HTTP client failed before receiving a usable response.
65    #[error("HTTP request failed: {0}")]
66    Http(reqwest::Error),
67
68    /// JSON serialization failed while rendering output.
69    #[error("failed to render JSON output: {0}")]
70    Json(#[from] serde_json::Error),
71}
72
73impl From<reqwest::Error> for Error {
74    fn from(error: reqwest::Error) -> Self {
75        Self::Http(error.without_url())
76    }
77}
78
79impl Error {
80    /// Returns a stable machine-readable error kind.
81    #[must_use]
82    pub const fn kind(&self) -> &'static str {
83        match self {
84            Self::MissingApiKey => "missing_api_key",
85            Self::InvalidBaseUrl(_) => "invalid_base_url",
86            Self::MissingArgument(_) => "missing_argument",
87            Self::Api { .. } => "api_error",
88            Self::RateLimited { .. } => "rate_limited",
89            Self::EmptyResult { .. } => "empty_result",
90            Self::EndpointUnavailable { .. } => "endpoint_unavailable",
91            Self::Http(_) => "http_error",
92            Self::Json(_) => "json_error",
93        }
94    }
95
96    /// Returns a process exit code for this error.
97    ///
98    /// Codes follow a simple convention:
99    /// - `2` - usage/argument error (missing required CLI argument)
100    /// - `3` - configuration error (missing API key, invalid base URL)
101    /// - `4` - network/HTTP error
102    /// - `5` - API error (server returned an error response, including rate limits)
103    /// - `6` - parse error (JSON deserialization failed)
104    /// - `7` - empty symbol result in strict mode
105    #[must_use]
106    pub fn exit_code(&self) -> ExitCode {
107        match self {
108            Self::MissingArgument(_) => ExitCode::from(2),
109            Self::MissingApiKey | Self::InvalidBaseUrl(_) => ExitCode::from(3),
110            Self::Http(_) => ExitCode::from(4),
111            Self::Api { .. } | Self::RateLimited { .. } | Self::EndpointUnavailable { .. } => {
112                ExitCode::from(5)
113            }
114            Self::Json(_) => ExitCode::from(6),
115            Self::EmptyResult { .. } => ExitCode::from(7),
116        }
117    }
118}
rusty_fmp/error.rs

rusty_fmp/
error.rs
