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}