mostro_core/error.rs
1//! Error taxonomy used across the crate.
2//!
3//! Errors surfaced to clients are modelled as [`MostroError`], which is split
4//! into two branches:
5//!
6//! * [`MostroError::MostroCantDo`] — a "soft" error: the request was
7//! well-formed but the server refuses to perform the action (e.g. the order
8//! is not in the right state). Clients should surface the inner
9//! [`CantDoReason`] to the user.
10//! * [`MostroError::MostroInternalErr`] — a "hard" error: something went
11//! wrong while processing the request (database failure, Nostr relay
12//! issue, malformed invoice, etc.). The inner [`ServiceError`] carries the
13//! diagnostic detail.
14//!
15//! Both inner enums implement [`Display`](std::fmt::Display) with
16//! human-readable messages suited for logging.
17
18use crate::prelude::*;
19
20/// Machine-readable reasons carried by a `CantDo` response.
21///
22/// Serialized in `snake_case` so clients can pattern-match on the value
23/// transported in [`crate::message::Payload::CantDo`].
24#[derive(Debug, Deserialize, Serialize, Clone, PartialEq, Eq)]
25#[serde(rename_all = "snake_case")]
26pub enum CantDoReason {
27 /// The provided signature is invalid or missing.
28 InvalidSignature,
29 /// The specified trade index does not exist or is invalid.
30 InvalidTradeIndex,
31 /// The provided amount is invalid or out of acceptable range.
32 InvalidAmount,
33 /// The provided invoice is malformed or expired.
34 InvalidInvoice,
35 /// The payment request is invalid or cannot be processed.
36 InvalidPaymentRequest,
37 /// The specified peer is invalid or not found.
38 InvalidPeer,
39 /// The rating value is invalid or out of range.
40 InvalidRating,
41 /// The text message is invalid or contains prohibited content.
42 InvalidTextMessage,
43 /// The order kind is invalid.
44 InvalidOrderKind,
45 /// The order status is invalid.
46 InvalidOrderStatus,
47 /// The provided public key is invalid.
48 InvalidPubkey,
49 /// One or more request parameters are invalid.
50 InvalidParameters,
51 /// The provided payload is the wrong shape for this action,
52 /// or carries values that cannot be processed (e.g. a
53 /// `BondResolution` requesting a slash against a side with no
54 /// active bond row). The caller should correct and resend.
55 InvalidPayload,
56 /// The targeted order has already been canceled.
57 OrderAlreadyCanceled,
58 /// User creation failed on the server side.
59 CantCreateUser,
60 /// The caller tried to operate on an order that does not belong to them.
61 IsNotYourOrder,
62 /// The requested action is not allowed in the order's current status.
63 NotAllowedByStatus,
64 /// The fiat amount is outside the allowed range for this order.
65 OutOfRangeFiatAmount,
66 /// The sats amount is outside the allowed range for this order.
67 OutOfRangeSatsAmount,
68 /// The caller tried to operate on a dispute that does not belong to them.
69 IsNotYourDispute,
70 /// A solver is being notified that an admin has taken over their dispute.
71 DisputeTakenByAdmin,
72 /// The caller is authenticated but lacks the permission for this action.
73 NotAuthorized,
74 /// A dispute could not be created (e.g. order not in a disputable state).
75 DisputeCreationError,
76 /// Generic "resource not found" error.
77 NotFound,
78 /// The dispute is in an invalid state for the requested action.
79 InvalidDisputeStatus,
80 /// The requested action is invalid.
81 InvalidAction,
82 /// The caller already has a pending order and cannot create another.
83 PendingOrderExists,
84 /// The fiat currency code is not accepted by this Mostro node.
85 InvalidFiatCurrency,
86 /// The caller is being rate-limited.
87 TooManyRequests,
88}
89
90/// Internal errors raised by services behind the Mostro API.
91///
92/// Unlike [`CantDoReason`], values of this enum are not expected to be
93/// forwarded verbatim to end users; they are meant for logs, telemetry and
94/// other server-to-server diagnostics.
95#[derive(Debug, PartialEq, Eq)]
96pub enum ServiceError {
97 /// Wraps an error returned by `nostr_sdk`.
98 NostrError(String),
99 /// The invoice string could not be parsed as a valid BOLT-11 invoice.
100 ParsingInvoiceError,
101 /// A numeric value could not be parsed.
102 ParsingNumberError,
103 /// The invoice has expired.
104 InvoiceExpiredError,
105 /// The invoice is otherwise invalid.
106 InvoiceInvalidError,
107 /// The invoice expiration time is below the minimum required.
108 MinExpirationTimeError,
109 /// The invoice amount is below the minimum allowed.
110 MinAmountError,
111 /// The invoice amount does not match the expected value.
112 WrongAmountError,
113 /// The price API did not answer in time.
114 NoAPIResponse,
115 /// The requested currency is not listed by the exchange API.
116 NoCurrency,
117 /// The exchange API returned a response that could not be parsed.
118 MalformedAPIRes,
119 /// Amount value is negative where only positives are allowed.
120 NegativeAmount,
121 /// A Lightning Address could not be parsed.
122 LnAddressParseError,
123 /// A Lightning Address payment was attempted with a wrong amount.
124 LnAddressWrongAmount,
125 /// A Lightning payment failed; the inner string carries the reason.
126 LnPaymentError(String),
127 /// Communication with the Lightning node failed.
128 LnNodeError(String),
129 /// Order id was not found in the database.
130 InvalidOrderId,
131 /// Database access failed; the inner string carries the detail.
132 DbAccessError(String),
133 /// The provided public key is invalid.
134 InvalidPubkey,
135 /// Hold-invoice operation failed; the inner string carries the detail.
136 HoldInvoiceError(String),
137 /// Could not update the order status in the database.
138 UpdateOrderStatusError,
139 /// The order status is invalid.
140 InvalidOrderStatus,
141 /// The order kind is invalid.
142 InvalidOrderKind,
143 /// A dispute already exists for this order.
144 DisputeAlreadyExists,
145 /// Could not publish the dispute Nostr event.
146 DisputeEventError,
147 /// The rating message itself is invalid.
148 InvalidRating,
149 /// The rating value is outside the accepted range.
150 InvalidRatingValue,
151 /// Failed to serialize or deserialize a [`crate::message::Message`].
152 MessageSerializationError,
153 /// The dispute id is invalid or unknown.
154 InvalidDisputeId,
155 /// The dispute status is invalid.
156 InvalidDisputeStatus,
157 /// The payload does not match the action.
158 InvalidPayload,
159 /// Any other unexpected error; inner string carries the detail.
160 UnexpectedError(String),
161 /// An environment variable could not be read or parsed.
162 EnvVarError(String),
163 /// Underlying I/O error.
164 IOError(String),
165 /// NIP-44/NIP-59 encryption failed.
166 EncryptionError(String),
167 /// NIP-44/NIP-59 decryption failed.
168 DecryptionError(String),
169}
170
171/// Top-level error type returned by the Mostro API surface.
172///
173/// Most public functions in this crate return `Result<T, MostroError>`.
174/// Match on the variants to distinguish between user-actionable "can't do"
175/// responses and internal service errors.
176#[derive(Debug, PartialEq, Eq)]
177pub enum MostroError {
178 /// An internal service-level error; diagnostic only.
179 MostroInternalErr(ServiceError),
180 /// A structured "can't do" response to surface to the user.
181 MostroCantDo(CantDoReason),
182}
183
184impl std::error::Error for MostroError {}
185
186impl std::fmt::Display for MostroError {
187 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
188 match self {
189 MostroError::MostroInternalErr(m) => write!(f, "Error caused by {}", m),
190 MostroError::MostroCantDo(m) => write!(f, "Sending cantDo message to user for {:?}", m),
191 }
192 }
193}
194
195impl std::fmt::Display for ServiceError {
196 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
197 match self {
198 ServiceError::ParsingInvoiceError => write!(f, "Incorrect invoice"),
199 ServiceError::ParsingNumberError => write!(f, "Error parsing the number"),
200 ServiceError::InvoiceExpiredError => write!(f, "Invoice has expired"),
201 ServiceError::MinExpirationTimeError => write!(f, "Minimal expiration time on invoice"),
202 ServiceError::InvoiceInvalidError => write!(f, "Invoice is invalid"),
203 ServiceError::MinAmountError => write!(f, "Minimal payment amount"),
204 ServiceError::WrongAmountError => write!(f, "The amount on this invoice is wrong"),
205 ServiceError::NoAPIResponse => write!(f, "Price API not answered - retry"),
206 ServiceError::NoCurrency => write!(f, "Currency requested is not present in the exchange list, please specify a fixed rate"),
207 ServiceError::MalformedAPIRes => write!(f, "Malformed answer from exchange quoting request"),
208 ServiceError::NegativeAmount => write!(f, "Negative amount is not valid"),
209 ServiceError::LnAddressWrongAmount => write!(f, "Ln address need amount of 0 sats - please check your order"),
210 ServiceError::LnAddressParseError => write!(f, "Ln address parsing error - please check your address"),
211 ServiceError::LnPaymentError(e) => write!(f, "Lightning payment failure cause: {}",e),
212 ServiceError::LnNodeError(e) => write!(f, "Lightning node connection failure caused by: {}",e),
213 ServiceError::InvalidOrderId => write!(f, "Order id not present in database"),
214 ServiceError::InvalidPubkey => write!(f, "Invalid pubkey"),
215 ServiceError::DbAccessError(e) => write!(f, "Error in database access: {}",e),
216 ServiceError::HoldInvoiceError(e) => write!(f, "Error holding invoice: {}",e),
217 ServiceError::UpdateOrderStatusError => write!(f, "Error updating order status"),
218 ServiceError::InvalidOrderStatus => write!(f, "Invalid order status"),
219 ServiceError::InvalidOrderKind => write!(f, "Invalid order kind"),
220 ServiceError::DisputeAlreadyExists => write!(f, "Dispute already exists"),
221 ServiceError::DisputeEventError => write!(f, "Error publishing dispute event"),
222 ServiceError::NostrError(e) => write!(f, "Error in nostr: {}",e),
223 ServiceError::InvalidRating => write!(f, "Invalid rating message"),
224 ServiceError::InvalidRatingValue => write!(f, "Invalid rating value"),
225 ServiceError::MessageSerializationError => write!(f, "Error serializing message"),
226 ServiceError::InvalidDisputeId => write!(f, "Invalid dispute id"),
227 ServiceError::InvalidDisputeStatus => write!(f, "Invalid dispute status"),
228 ServiceError::InvalidPayload => write!(f, "Invalid payload"),
229 ServiceError::UnexpectedError(e) => write!(f, "Unexpected error: {}", e),
230 ServiceError::EnvVarError(e) => write!(f, "Environment variable error: {}", e),
231 ServiceError::IOError(e) => write!(f, "IO error: {}", e),
232 ServiceError::EncryptionError(e) => write!(f, "Encryption error: {}", e),
233 ServiceError::DecryptionError(e) => write!(f, "Decryption error: {}", e),
234 }
235 }
236}
237
238#[cfg(test)]
239mod tests {
240 use super::*;
241
242 #[test]
243 fn invalid_payload_serializes_to_snake_case() {
244 let json = serde_json::to_string(&CantDoReason::InvalidPayload).unwrap();
245 assert_eq!(json, "\"invalid_payload\"");
246 let round: CantDoReason = serde_json::from_str(&json).unwrap();
247 assert_eq!(round, CantDoReason::InvalidPayload);
248 }
249}