commit 13c6ede78f2ecdb1336f5b5863fc52c3ea123752
parent a72cb0208c7202a69af1c886d08f2f568041df89
Author: Florian Dold <dold@taler.net>
Date: Thu, 30 Jul 2026 14:18:45 +0200
wallet-core: document the expected errors of each request
Only codes a caller can act on inline are listed, since an entry here also
turns callForResult from throwing into a Result for that code.
Diffstat:
1 file changed, 263 insertions(+), 0 deletions(-)
diff --git a/packages/taler-wallet-core/src/wallet-api-types.ts b/packages/taler-wallet-core/src/wallet-api-types.ts
@@ -1673,10 +1673,273 @@ export type ForceRefreshOp = {
/**
* Mapping from the wallet-core request type to a list of expected errors.
+ *
+ * "Expected" means: a caller can reasonably react to this error inline, so
+ * {@link WalletCoreApiClient.callForResult} hands it back as a
+ * `Result.error` instead of throwing. Everything not listed here — network
+ * failures, protocol violations, internal errors — keeps throwing, because
+ * there is nothing specific a caller could do about it.
+ *
+ * Adding a code here widens `WalletCoreErrorType<Op>` for that operation, so
+ * only list what a UI or CLI actually needs to branch on. This is not meant
+ * to be an exhaustive catalogue of everything an operation can raise.
*/
export const walletApiExpectedErrors = {
+ // --- Transactions -------------------------------------------------------
+
+ [WalletApiOperation.GetTransactionById]: [
+ TalerErrorCode.WALLET_TRANSACTION_NOT_FOUND,
+ TalerErrorCode.WALLET_CORE_API_BAD_REQUEST,
+ ],
+ [WalletApiOperation.AbortTransaction]: [
+ TalerErrorCode.WALLET_TRANSACTION_NOT_FOUND,
+ TalerErrorCode.WALLET_TRANSACTION_ACTION_UNSUPPORTED,
+ TalerErrorCode.WALLET_REQUEST_TRANSACTION_STATE_UNSUPPORTED,
+ ],
+ [WalletApiOperation.FailTransaction]: [
+ TalerErrorCode.WALLET_TRANSACTION_NOT_FOUND,
+ TalerErrorCode.WALLET_TRANSACTION_ACTION_UNSUPPORTED,
+ TalerErrorCode.WALLET_REQUEST_TRANSACTION_STATE_UNSUPPORTED,
+ ],
+ [WalletApiOperation.SuspendTransaction]: [
+ TalerErrorCode.WALLET_TRANSACTION_NOT_FOUND,
+ TalerErrorCode.WALLET_TRANSACTION_ACTION_UNSUPPORTED,
+ TalerErrorCode.WALLET_REQUEST_TRANSACTION_STATE_UNSUPPORTED,
+ ],
+ [WalletApiOperation.ResumeTransaction]: [
+ TalerErrorCode.WALLET_TRANSACTION_NOT_FOUND,
+ TalerErrorCode.WALLET_TRANSACTION_ACTION_UNSUPPORTED,
+ TalerErrorCode.WALLET_REQUEST_TRANSACTION_STATE_UNSUPPORTED,
+ ],
+ [WalletApiOperation.DeleteTransaction]: [
+ TalerErrorCode.WALLET_TRANSACTION_NOT_FOUND,
+ ],
+ [WalletApiOperation.RetryTransaction]: [
+ TalerErrorCode.WALLET_TRANSACTION_NOT_FOUND,
+ ],
+
+ // --- Payment ------------------------------------------------------------
+
+ [WalletApiOperation.PreparePayForUriV2]: [
+ TalerErrorCode.WALLET_TALER_URI_MALFORMED,
+ TalerErrorCode.WALLET_MERCHANT_ORDER_NOT_FOUND,
+ TalerErrorCode.WALLET_ORDER_ALREADY_CLAIMED,
+ TalerErrorCode.WALLET_ORDER_ALREADY_PAID,
+ TalerErrorCode.WALLET_CONTRACT_TERMS_MALFORMED,
+ TalerErrorCode.WALLET_CONTRACT_TERMS_UNSUPPORTED,
+ ],
+ [WalletApiOperation.PreparePayForTemplateV2]: [
+ TalerErrorCode.WALLET_TALER_URI_MALFORMED,
+ TalerErrorCode.WALLET_CONTRACT_TERMS_UNSUPPORTED,
+ ],
+ [WalletApiOperation.CheckPayForTemplate]: [
+ TalerErrorCode.WALLET_TALER_URI_MALFORMED,
+ TalerErrorCode.WALLET_CONTRACT_TERMS_UNSUPPORTED,
+ ],
[WalletApiOperation.GetChoicesForPayment]: [
TalerErrorCode.WALLET_REQUEST_TRANSACTION_STATE_UNSUPPORTED,
+ TalerErrorCode.WALLET_TRANSACTION_NOT_FOUND,
+ ],
+ [WalletApiOperation.ConfirmPay]: [
+ TalerErrorCode.WALLET_PAY_MERCHANT_INSUFFICIENT_BALANCE,
+ TalerErrorCode.WALLET_TRANSACTION_NOT_FOUND,
+ TalerErrorCode.WALLET_REQUEST_TRANSACTION_STATE_UNSUPPORTED,
+ TalerErrorCode.WALLET_CORE_API_BAD_REQUEST,
+ ],
+ [WalletApiOperation.SharePayment]: [
+ TalerErrorCode.WALLET_PURCHASE_NOT_FOUND,
+ TalerErrorCode.WALLET_TRANSACTION_NOT_FOUND,
+ TalerErrorCode.WALLET_REQUEST_TRANSACTION_STATE_UNSUPPORTED,
+ ],
+ [WalletApiOperation.StartRefundQueryForUri]: [
+ TalerErrorCode.WALLET_TALER_URI_MALFORMED,
+ TalerErrorCode.WALLET_PURCHASE_NOT_FOUND,
+ ],
+
+ // --- Withdrawal ---------------------------------------------------------
+
+ [WalletApiOperation.PrepareBankIntegratedWithdrawal]: [
+ TalerErrorCode.WALLET_TALER_URI_MALFORMED,
+ ],
+ [WalletApiOperation.GetWithdrawalDetailsForUri]: [
+ TalerErrorCode.WALLET_TALER_URI_MALFORMED,
+ ],
+ [WalletApiOperation.GetWithdrawalDetailsForAmount]: [
+ TalerErrorCode.WALLET_EXCHANGE_ENTRY_NOT_FOUND,
+ TalerErrorCode.WALLET_EXCHANGE_TOS_NOT_ACCEPTED,
+ TalerErrorCode.GENERIC_CURRENCY_MISMATCH,
+ ],
+ [WalletApiOperation.ConfirmWithdrawal]: [
+ TalerErrorCode.WALLET_KYC_LIMIT_EXCEEDED,
+ TalerErrorCode.WALLET_NO_SUITABLE_EXCHANGE,
+ TalerErrorCode.WALLET_EXCHANGE_TOS_NOT_ACCEPTED,
+ TalerErrorCode.WALLET_TRANSACTION_NOT_FOUND,
+ TalerErrorCode.GENERIC_CURRENCY_MISMATCH,
+ TalerErrorCode.WALLET_CORE_API_BAD_REQUEST,
+ ],
+ [WalletApiOperation.AcceptManualWithdrawal]: [
+ TalerErrorCode.WALLET_KYC_LIMIT_EXCEEDED,
+ TalerErrorCode.WALLET_EXCHANGE_TOS_NOT_ACCEPTED,
+ TalerErrorCode.GENERIC_CURRENCY_MISMATCH,
+ ],
+ [WalletApiOperation.PrepareWithdrawExchange]: [
+ TalerErrorCode.WALLET_TALER_URI_MALFORMED,
+ TalerErrorCode.GENERIC_CURRENCY_MISMATCH,
+ ],
+
+ // --- Deposit ------------------------------------------------------------
+
+ [WalletApiOperation.CheckDeposit]: [
+ TalerErrorCode.GENERIC_PAYTO_URI_MALFORMED,
+ TalerErrorCode.WALLET_NO_SUITABLE_EXCHANGE,
+ TalerErrorCode.WALLET_DEPOSIT_GROUP_INSUFFICIENT_BALANCE,
+ ],
+ [WalletApiOperation.CreateDepositGroup]: [
+ TalerErrorCode.GENERIC_PAYTO_URI_MALFORMED,
+ TalerErrorCode.WALLET_NO_SUITABLE_EXCHANGE,
+ TalerErrorCode.WALLET_DEPOSIT_GROUP_INSUFFICIENT_BALANCE,
+ TalerErrorCode.WALLET_KYC_LIMIT_EXCEEDED,
+ ],
+
+ // --- Peer-to-peer -------------------------------------------------------
+
+ [WalletApiOperation.PreparePeerPushCredit]: [
+ TalerErrorCode.WALLET_PEER_CONTRACT_NOT_FOUND,
+ TalerErrorCode.WALLET_PEER_PUSH_CREDIT_PURSE_GONE,
+ TalerErrorCode.WALLET_TALER_URI_MALFORMED,
+ TalerErrorCode.WALLET_TRANSACTION_NOT_FOUND,
+ ],
+ [WalletApiOperation.ConfirmPeerPushCredit]: [
+ TalerErrorCode.WALLET_KYC_LIMIT_EXCEEDED,
+ TalerErrorCode.WALLET_EXCHANGE_TOS_NOT_ACCEPTED,
+ TalerErrorCode.WALLET_TRANSACTION_NOT_FOUND,
+ ],
+ [WalletApiOperation.PreparePeerPullDebit]: [
+ TalerErrorCode.WALLET_PEER_CONTRACT_NOT_FOUND,
+ TalerErrorCode.WALLET_PEER_PULL_DEBIT_PURSE_GONE,
+ TalerErrorCode.WALLET_PEER_PULL_DEBIT_ALREADY_PAID,
+ TalerErrorCode.WALLET_PEER_PULL_PAYMENT_INSUFFICIENT_BALANCE,
+ TalerErrorCode.WALLET_TALER_URI_MALFORMED,
+ TalerErrorCode.WALLET_TRANSACTION_NOT_FOUND,
+ ],
+ [WalletApiOperation.ConfirmPeerPullDebit]: [
+ TalerErrorCode.WALLET_PEER_PULL_PAYMENT_INSUFFICIENT_BALANCE,
+ TalerErrorCode.WALLET_TRANSACTION_NOT_FOUND,
+ ],
+ [WalletApiOperation.CheckPeerPushDebit]: [
+ TalerErrorCode.WALLET_PEER_PUSH_PAYMENT_INSUFFICIENT_BALANCE,
+ TalerErrorCode.WALLET_NO_SUITABLE_EXCHANGE,
+ ],
+ [WalletApiOperation.CheckPeerPushDebitV2]: [
+ TalerErrorCode.WALLET_PEER_PUSH_PAYMENT_INSUFFICIENT_BALANCE,
+ TalerErrorCode.WALLET_NO_SUITABLE_EXCHANGE,
+ ],
+ [WalletApiOperation.InitiatePeerPushDebit]: [
+ TalerErrorCode.WALLET_PEER_PUSH_PAYMENT_INSUFFICIENT_BALANCE,
+ TalerErrorCode.WALLET_NO_SUITABLE_EXCHANGE,
+ TalerErrorCode.WALLET_CORE_API_BAD_REQUEST,
+ ],
+ [WalletApiOperation.CheckPeerPullCredit]: [
+ TalerErrorCode.WALLET_NO_SUITABLE_EXCHANGE,
+ TalerErrorCode.WALLET_CORE_API_BAD_REQUEST,
+ ],
+ [WalletApiOperation.InitiatePeerPullCredit]: [
+ TalerErrorCode.WALLET_NO_SUITABLE_EXCHANGE,
+ TalerErrorCode.WALLET_KYC_LIMIT_EXCEEDED,
+ TalerErrorCode.WALLET_EXCHANGE_TOS_NOT_ACCEPTED,
+ TalerErrorCode.WALLET_CORE_API_BAD_REQUEST,
+ ],
+
+ // --- Exchanges ----------------------------------------------------------
+
+ [WalletApiOperation.AddExchange]: [
+ TalerErrorCode.WALLET_TALER_URI_MALFORMED,
+ TalerErrorCode.WALLET_EXCHANGE_UNAVAILABLE,
+ TalerErrorCode.WALLET_EXCHANGE_SIGNATURE_INVALID,
+ TalerErrorCode.WALLET_CORE_API_BAD_REQUEST,
+ ],
+ [WalletApiOperation.GetExchangeEntryByUrl]: [
+ TalerErrorCode.WALLET_EXCHANGE_ENTRY_NOT_FOUND,
+ ],
+ [WalletApiOperation.GetExchangeDetailedInfo]: [
+ TalerErrorCode.WALLET_EXCHANGE_ENTRY_NOT_FOUND,
+ ],
+ [WalletApiOperation.GetExchangeTos]: [
+ TalerErrorCode.WALLET_EXCHANGE_ENTRY_NOT_FOUND,
+ ],
+ [WalletApiOperation.DeleteExchange]: [
+ TalerErrorCode.WALLET_EXCHANGE_ENTRY_NOT_FOUND,
+ TalerErrorCode.WALLET_EXCHANGE_ENTRY_USED,
+ ],
+ [WalletApiOperation.UpdateExchangeEntry]: [
+ TalerErrorCode.WALLET_EXCHANGE_ENTRY_NOT_FOUND,
+ TalerErrorCode.WALLET_EXCHANGE_ENTRY_UPDATE_CONFLICT,
+ TalerErrorCode.WALLET_EXCHANGE_UNAVAILABLE,
+ ],
+
+ // --- Bank accounts ------------------------------------------------------
+
+ [WalletApiOperation.GetBankAccountById]: [
+ TalerErrorCode.WALLET_BANK_ACCOUNT_NOT_FOUND,
+ ],
+ [WalletApiOperation.ForgetBankAccount]: [
+ TalerErrorCode.WALLET_BANK_ACCOUNT_NOT_FOUND,
+ ],
+ [WalletApiOperation.AddBankAccount]: [
+ TalerErrorCode.GENERIC_PAYTO_URI_MALFORMED,
+ ],
+
+ // --- Tokens (discounts and subscriptions) -------------------------------
+
+ [WalletApiOperation.DeleteDiscount]: [TalerErrorCode.WALLET_TOKENS_IN_USE],
+ [WalletApiOperation.DeleteSubscription]: [
+ TalerErrorCode.WALLET_TOKENS_IN_USE,
+ ],
+
+ // --- Mailbox and aliases ------------------------------------------------
+
+ [WalletApiOperation.InitializeMailbox]: [
+ TalerErrorCode.WALLET_MAILBOX_UNAVAILABLE,
+ TalerErrorCode.GENERIC_FORBIDDEN,
+ ],
+ [WalletApiOperation.RefreshMailbox]: [
+ TalerErrorCode.WALLET_MAILBOX_UNAVAILABLE,
+ ],
+ [WalletApiOperation.SendTalerUriMailboxMessage]: [
+ TalerErrorCode.WALLET_MAILBOX_UNAVAILABLE,
+ ],
+ [WalletApiOperation.RegisterAlias]: [
+ TalerErrorCode.WALLET_ALIAS_REGISTRATION_FAILED,
+ ],
+ [WalletApiOperation.CompleteRegisterAlias]: [
+ TalerErrorCode.WALLET_ALIAS_REGISTRATION_FAILED,
+ TalerErrorCode.GENERIC_FORBIDDEN,
+ ],
+ [WalletApiOperation.LookupAlias]: [
+ TalerErrorCode.WALLET_ALIAS_REGISTRATION_FAILED,
+ ],
+
+ // --- Database maintenance -----------------------------------------------
+
+ [WalletApiOperation.ExportDbToFile]: [
+ TalerErrorCode.WALLET_DB_BACKEND_UNSUPPORTED,
+ ],
+ [WalletApiOperation.ImportDbFromFile]: [
+ TalerErrorCode.WALLET_DB_BACKEND_UNSUPPORTED,
+ TalerErrorCode.WALLET_CORE_API_BAD_REQUEST,
+ ],
+ [WalletApiOperation.CreateStoredBackup]: [
+ TalerErrorCode.WALLET_DB_BACKEND_UNSUPPORTED,
+ ],
+ [WalletApiOperation.ListStoredBackups]: [
+ TalerErrorCode.WALLET_DB_BACKEND_UNSUPPORTED,
+ ],
+ [WalletApiOperation.DeleteStoredBackup]: [
+ TalerErrorCode.WALLET_DB_BACKEND_UNSUPPORTED,
+ ],
+ [WalletApiOperation.RecoverStoredBackup]: [
+ TalerErrorCode.WALLET_DB_BACKEND_UNSUPPORTED,
+ TalerErrorCode.WALLET_CORE_API_BAD_REQUEST,
],
} as const;
