Skip to main content

atp_client/
error.rs

1use serde::{Deserialize, Serialize};
2use thiserror::Error;
3
4#[derive(Debug, Clone, Serialize, Deserialize)]
5/// ATP's stable JSON error envelope.
6pub struct ApiErrorBody {
7    /// Structured error detail returned by ATP.
8    pub error: ApiErrorDetail,
9}
10
11#[derive(Debug, Clone, Serialize, Deserialize)]
12/// Machine-readable ATP error detail.
13pub struct ApiErrorDetail {
14    /// Stable application error code.
15    pub code: String,
16    /// Human-readable diagnostic message; do not branch on this value.
17    pub message: String,
18    /// Request identifier used to correlate ATP logs and support cases.
19    pub request_id: String,
20}
21
22#[derive(Debug, Error)]
23/// Errors produced by client configuration, transport, or the ATP API.
24pub enum SdkError {
25    /// Client-side configuration or input is invalid.
26    #[error("invalid ATP SDK configuration: {0}")]
27    Config(String),
28    /// An HTTP attempt exceeded its configured deadline.
29    #[error("ATP request timed out")]
30    Timeout,
31    /// The request failed before a usable HTTP response was received.
32    #[error("ATP transport failed: {0}")]
33    Transport(String),
34    /// ATP returned a response that did not match the public wire contract.
35    #[error("ATP response could not be decoded: {0}")]
36    Decode(String),
37    /// The tenant API key was missing, disabled, or invalid.
38    #[error("ATP rejected credentials")]
39    Unauthorized,
40    /// The requested ATP resource does not exist in this tenant.
41    #[error("ATP resource was not found")]
42    NotFound,
43    /// Available credit buckets could not cover a debit.
44    #[error("insufficient credits")]
45    InsufficientCredits,
46    /// Current state conflicts with the requested operation.
47    #[error("ATP request conflicts with current state")]
48    Conflict,
49    /// ATP throttled the request.
50    #[error("ATP rate limit exceeded")]
51    RateLimited {
52        /// Parsed `Retry-After` delay when supplied by ATP.
53        retry_after_seconds: Option<u64>,
54    },
55    /// A structured API failure without a more specific SDK variant.
56    #[error("ATP API error {code}: {message} (request {request_id})")]
57    Api {
58        /// HTTP status code.
59        status: u16,
60        /// Stable ATP application error code.
61        code: String,
62        /// Human-readable diagnostic message.
63        message: String,
64        /// Server request identifier for log correlation.
65        request_id: String,
66    },
67}
68
69impl SdkError {
70    /// Returns whether replaying this request may succeed without changing its inputs.
71    ///
72    /// The SDK applies this only to GET operations; callers control write retries.
73    pub fn is_retryable(&self) -> bool {
74        matches!(
75            self,
76            Self::Timeout
77                | Self::Transport(_)
78                | Self::RateLimited { .. }
79                | Self::Api {
80                    status: 502..=504,
81                    ..
82                }
83        )
84    }
85}
86
87/// Result alias used by all SDK operations.
88pub type SdkResult<T> = std::result::Result<T, SdkError>;
89
90#[cfg(test)]
91mod tests {
92    use super::*;
93    #[test]
94    fn cross_language_error_fixture_decodes() {
95        let value: ApiErrorBody = serde_json::from_str(include_str!(
96            "../../../sdk-conformance/error-insufficient-credits.json"
97        ))
98        .unwrap();
99        assert_eq!(value.error.code, "insufficient_credits");
100    }
101}