taler-android

Android apps for GNU Taler (wallet, PoS, cashier)
Log | Files | Refs | README | LICENSE

error-code-registry-behind-wallet-core.md (4340B)


      1 <!--
      2   This file is part of GNU Taler
      3   (C) 2026 Taler Systems S.A.
      4 
      5   GNU Taler is free software; you can redistribute it and/or modify it under the
      6   terms of the GNU General Public License as published by the Free Software
      7   Foundation; either version 3, or (at your option) any later version.
      8 
      9   GNU Taler is distributed in the hope that it will be useful, but WITHOUT ANY
     10   WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
     11   A PARTICULAR PURPOSE.  See the GNU General Public License for more details.
     12 
     13   You should have received a copy of the GNU General Public License along with
     14   GNU Taler; see the file COPYING.  If not, see <http://www.gnu.org/licenses/>
     15 -->
     16 
     17 # The app's error-code registry is behind the wallet-core it ships
     18 
     19 Found by tallying every error reply in the simulator's logs
     20 (`simulator/coverage/operations.py`): two of the four codes the wallet-core in
     21 `net.taler:qtart:1.6.42` returned during normal scenarios are not in
     22 `wallet/src/main/java/net/taler/wallet/backend/TalerErrorCode.kt`.
     23 
     24 **Severity: low, but it grows.** `TalerErrorInfo.rawCode` keeps the number, so
     25 nothing crashes and the hint text still reaches the user; what is lost is the
     26 ability to recognise the error. Any `code == TalerErrorCode.X` branch added for
     27 one of these cases would silently never match, and triage reads "UNKNOWN".
     28 
     29 ## What was observed
     30 
     31 | Operation | Code returned | Name upstream |
     32 | --- | --- | --- |
     33 | `getTransactionById` | 7052 | `WALLET_TRANSACTION_NOT_FOUND` |
     34 | `startRefundQueryForUri` | 7051 | `WALLET_PURCHASE_NOT_FOUND` |
     35 
     36 Neither number appears in `TalerErrorCode.kt`, so both arrive as
     37 `TalerErrorCode.UNKNOWN` with `rawCode` set.
     38 
     39 ## The size of the gap
     40 
     41 Against the registry in the `taler-typescript-core` checkout (the source the
     42 bundled wallet-core is built from), the app is missing **141 codes**
     43 in total, of which **26** are in the wallet's own 7xxx range
     44 and therefore reachable from the app:
     45 
     46 | Code | Name |
     47 | --- | --- |
     48 | 7050 | `WALLET_PAY_MERCHANT_INSUFFICIENT_BALANCE` |
     49 | 7051 | `WALLET_PURCHASE_NOT_FOUND` |
     50 | 7052 | `WALLET_TRANSACTION_NOT_FOUND` |
     51 | 7053 | `WALLET_TRANSACTION_ACTION_UNSUPPORTED` |
     52 | 7054 | `WALLET_KYC_LIMIT_EXCEEDED` |
     53 | 7055 | `WALLET_NO_SUITABLE_EXCHANGE` |
     54 | 7056 | `WALLET_BANK_ACCOUNT_NOT_FOUND` |
     55 | 7057 | `WALLET_PEER_CONTRACT_NOT_FOUND` |
     56 | 7058 | `WALLET_PEER_PUSH_CREDIT_PURSE_GONE` |
     57 | 7059 | `WALLET_PEER_PULL_DEBIT_ALREADY_PAID` |
     58 | 7060 | `WALLET_TOKENS_IN_USE` |
     59 | 7061 | `WALLET_DB_BACKEND_UNSUPPORTED` |
     60 | 7062 | `WALLET_MAILBOX_UNAVAILABLE` |
     61 | 7063 | `WALLET_ALIAS_REGISTRATION_FAILED` |
     62 | 7064 | `WALLET_CONTRACT_TERMS_UNSUPPORTED` |
     63 | 7065 | `WALLET_EXCHANGE_SIGNATURE_INVALID` |
     64 | 7066 | `WALLET_EXCHANGE_KEYS_NOT_ACCEPTED` |
     65 | 7067 | `WALLET_EXCHANGE_NO_KEY_CHANGE_PENDING` |
     66 | 7068 | `WALLET_EXCHANGE_KEY_CHANGE_MISMATCH` |
     67 | 7069 | `WALLET_PEER_PUSH_PAYMENT_QUOTE_CHANGED` |
     68 | 7070 | `WALLET_TRANSACTION_COMPLETED_BY_OTHER_WALLET` |
     69 | 7071 | `WALLET_REFRESH_GROUP_FAILED` |
     70 | 7072 | `WALLET_RECOUP_GROUP_FAILED` |
     71 | 7073 | `WALLET_REFUND_GROUP_FAILED` |
     72 | 7074 | `WALLET_TRANSACTION_RECOVERY_FAILED` |
     73 | 7075 | `WALLET_TRANSACTION_DEPENDENCY_FAILED` |
     74 
     75 ## Reproduce by hand
     76 
     77 ```bash
     78 # Codes the app knows nothing about, yet wallet-core can return:
     79 grep -c 'WALLET_TRANSACTION_NOT_FOUND' \
     80   wallet/src/main/java/net/taler/wallet/backend/TalerErrorCode.kt   # 0
     81 grep -c '7052' \
     82   wallet/src/main/java/net/taler/wallet/backend/TalerErrorCode.kt   # 0
     83 ```
     84 
     85 To see one arrive, follow `delete-transaction-requeries-deleted-id.md`: deleting
     86 a transaction logs an error with `"code":7052`.
     87 
     88 ## Reproduce with the simulator
     89 
     90 ```bash
     91 ssh root@tripwire.taler.net
     92 cd /opt/taler-sim/coverage && python3 operations.py /opt/taler-sim/run/out
     93 ```
     94 
     95 The "operations that returned an error, with codes" section lists each code
     96 observed, by operation.
     97 
     98 ## Suggested fix
     99 
    100 `TalerErrorCode.kt` carries an LGPL header and is a transcription of the GANA
    101 `gnu-taler-error-codes` registry, so it should be regenerated from that registry
    102 rather than extended by hand — ideally pinned to the same release as the
    103 `qtart` version in `wallet/build.gradle`, since that is what decides which
    104 codes can actually arrive. A check that fails the build when the bundled
    105 wallet-core knows a code the registry does not would keep the two from drifting
    106 again.