wallet: Introduce WalletError with machine-readable error code

diff --git a/src/wallet/types.h b/src/wallet/types.h
index 09ad4a0a..e4cbab3b 100644
--- a/src/wallet/types.h
+++ b/src/wallet/types.h
@@ -15,6 +15,7 @@
 #define BITCOIN_WALLET_TYPES_H
 
 #include <policy/fees/block_policy_estimator.h>
+#include <util/translation.h>
 
 namespace wallet {
 /**
@@ -42,6 +43,33 @@ struct CreatedTransactionResult
             : tx(_tx), fee(_fee), fee_calc(_fee_calc), change_pos(_change_pos) {}
 };
 
+//! Machine-readable wallet error codes.
+//!
+//! @note Add new codes only when callers need to handle the condition
+//! differently. For errors that should only be displayed to the user, use
+//! WalletErrorCode::GenericError and provide the user-facing details in WalletError::message.
+enum class WalletErrorCode {
+    //! Generic wallet error. Callers may present the accompanying message to
+    //! the user.
+    GenericError,
+
+    //! The wallet is locked and the operation requires access to private keys.
+    //! Callers may ask the user to unlock the wallet and retry the operation.
+    UnlockNeeded,
+};
+
+//! Wallet-layer error with both programmatic and user-facing information.
+//!
+//! Wallet methods should return a specific WalletErrorCode only when callers
+//! can handle that condition differently. Otherwise, use WalletErrorCode::GenericError
+//! and describe the failure in `message`.
+struct WalletError {
+    //! Machine-readable error code for callers that need programmatic handling.
+    WalletErrorCode code;
+    //! User-facing translated error message
+    bilingual_str message;
+};
+
 } // namespace wallet
 
 #endif // BITCOIN_WALLET_TYPES_H