Update bank spec

2 files changed, 176 insertions, 165 deletions

diff --git a/core/api-bank-integration.rst b/core/api-bank-integration.rst
index 0950b7c4..6b1f18d6 100644
--- a/core/api-bank-integration.rst
+++ b/core/api-bank-integration.rst
@@ -83,6 +83,8 @@ for the withdrawal operation (the ``wopid``) to interact with the withdrawal ope
   :http:statuscode:`200 OK`:
     The withdrawal operation is known to the bank, and details are given
     in the `BankWithdrawalOperationStatus` response body.
+  :http:statuscode:`404 Not found`:
+    The operation was not found
 
   **Details:**
 
@@ -143,8 +145,12 @@ for the withdrawal operation (the ``wopid``) to interact with the withdrawal ope
     The response is a `BankWithdrawalOperationPostResponse`.
   :http:statuscode:`404 Not found`:
     The bank does not know about a withdrawal operation with the specified ``wopid``.
-  :http:statuscode:`409 Conflict` (New):
-    The wallet selected a different exchange or reserve public key under the same withdrawal ID.
+  :http:statuscode:`409 Conflict`:
+    * ``TALER_EC_BANK_WITHDRAWAL_OPERATION_RESERVE_SELECTION_CONFLICT`` : 
+        The wallet selected a different exchange or reserve public key under the same withdrawal ID.
+    * ``TALER_EC_BANK_DUPLICATE_RESERVE_PUB_SUBJECT`` : the reserve public key is already used.
+    * ``TALER_EC_BANK_ACCOUNT_NOT_FOUND`` : the selected exchange account was not found.
+    * ``TALER_EC_BANK_ACCOUNT_IS_NOT_EXCHANGE`` : the selected account is not an exchange.
 
   **Details:**
 
diff --git a/core/api-corebank.rst b/core/api-corebank.rst
index a207b2d9..efc28fe8 100644
--- a/core/api-corebank.rst
+++ b/core/api-corebank.rst
@@ -118,81 +118,82 @@ Account Management
 
 .. http:post:: /accounts
 
-   Create a new bank account.  Depending on the configuration,
-   the account creation is self-serve, or only restricted to
-   the administrators.
+  Create a new bank account.  Depending on the configuration,
+  the account creation is self-serve, or only restricted to
+  the administrators.
 
-   **Request:**
+  **Request:**
 
-   .. ts:def:: RegisterAccountRequest
-
-     interface RegisterAccountRequest {
-       // Username
-       username: string;
-
-       // Password.
-       password: string;
-
-       // Legal name of the account owner
-       name: string;
-
-       // Defaults to false.
-       is_public?: boolean;
-
-       // Is this a taler exchange account?
-       // If true:
-       // - incoming transactions to the account that do not
-       //   have a valid reserve public key are automatically
-       // - the account provides the taler-wire-gateway-api endpoints
-       // Defaults to false.
-       is_taler_exchange?: boolean;
-
-       // Addresses where to send the TAN for transactions.
-       // Currently only used for cashouts.
-       // If missing, cashouts will fail.
-       // In the future, might be used for other transactions
-       // as well.
-       challenge_contact_data?: ChallengeContactData;
-
-       // 'payto' address pointing a bank account
-       // external to the bank.
-       // Payments will be sent to this bank account
-       // when the user wants to convert the local currency
-       // back to fiat currency outside bank.
-       cashout_payto_uri?: string;
-
-       // Internal payto URI of this bank account.
-       // Used mostly for testing.
-       internal_payto_uri?: string;
-     }
+  .. ts:def:: RegisterAccountRequest
 
-   .. ts:def:: ChallengeContactData
+    interface RegisterAccountRequest {
+      // Username
+      username: string;
 
-     interface ChallengeContactData {
+      // Password.
+      password: string;
 
-       // E-Mail address
-       email?: EmailAddress;
+      // Legal name of the account owner
+      name: string;
 
-       // Phone number.
-       phone?: PhoneNumber;
-     }
+      // Defaults to false.
+      is_public?: boolean;
+
+      // Is this a taler exchange account?
+      // If true:
+      // - incoming transactions to the account that do not
+      //   have a valid reserve public key are automatically
+      // - the account provides the taler-wire-gateway-api endpoints
+      // Defaults to false.
+      is_taler_exchange?: boolean;
+
+      // Addresses where to send the TAN for transactions.
+      // Currently only used for cashouts.
+      // If missing, cashouts will fail.
+      // In the future, might be used for other transactions
+      // as well.
+      challenge_contact_data?: ChallengeContactData;
+
+      // 'payto' address pointing a bank account
+      // external to the bank.
+      // Payments will be sent to this bank account
+      // when the user wants to convert the local currency
+      // back to fiat currency outside bank.
+      cashout_payto_uri?: string;
 
+      // Internal payto URI of this bank account.
+      // Used mostly for testing.
+      internal_payto_uri?: string;
+    }
 
-   **Response:**
+  .. ts:def:: ChallengeContactData
 
-   :http:statuscode:`201 Created`:
-     The account was successfully created.
-   :http:statuscode:`400 Bad request`:
-     Input data was invalid.  For example, the client specified a invalid
-     phone number or e-mail address.
-   :http:statuscode:`403 Forbidden`:
-     The response should indicate one of the following reasons.
+    interface ChallengeContactData {
 
-   * A reserved username was attempted, like ``admin`` or ``bank``.
-   * An unauthorized user tried to create the account
+      // E-Mail address
+      email?: EmailAddress;
+
+      // Phone number.
+      phone?: PhoneNumber;
+    }
 
-   :http:statuscode:`409 Conflict`:
-     The internal account payto URI or username already exists.
+
+  **Response:**
+
+  :http:statuscode:`201 Created`:
+    The account was successfully created.
+  :http:statuscode:`400 Bad request`:
+    Input data was invalid.  For example, the client specified a invalid
+    phone number or e-mail address.
+  :http:statuscode:`403 Forbidden`:
+    The response should indicate one of the following reasons.
+
+    * A reserved username was attempted, like ``admin`` or ``bank``.
+    * An unauthorized user tried to create the account
+  :http:statuscode:`409 Conflict`:
+    * ``TALER_EC_BANK_REGISTER_USERNAME_REUSE`` : username already used.
+    * ``TALER_EC_BANK_REGISTER_PAYTO_URI_REUSE`` : payto URI already used.
+    * ``TALER_EC_BANK_UNALLOWED_DEBIT`` : admin account does not have sufficient funds to grant bonus.
 
 .. _delete-account:
 
@@ -211,61 +212,58 @@ Account Management
     ``admin`` or ``bank``, or the client didn't have the rights to this
     call.
   :http:statuscode:`404 Not found`:
-    The username was not found.
-  :http:statuscode:`412 Precondition failed`:
-    The balance was not zero.
+    The account pointed by ``$USERNAME`` was not found.
+  :http:statuscode:`409 Conflict`:
+    The account balance was not zero.
 
 
 .. _account-reconfig:
 
 .. http:patch:: /accounts/$USERNAME
 
-   Allows reconfiguring the account data of ``$USERNAME``.
-
-   **Request:**
-
-   .. ts:def:: AccountReconfiguration
+  Allows reconfiguring the account data of ``$USERNAME``.
 
-     interface AccountReconfiguration {
+  **Request:**
 
-       // Addresses where to send the TAN for transactions.
-       // Currently only used for cashouts.
-       // If missing, cashouts will fail.
-       // In the future, might be used for other transactions
-       // as well.
-       challenge_contact_data?: ChallengeContactData;
+  .. ts:def:: AccountReconfiguration
 
-       // 'payto' address pointing a bank account
-       // external to the bank.
-       // Payments will be sent to this bank account
-       // when the user wants to convert the local currency
-       // back to fiat currency outside the bank.
-       cashout_address?: string;
+    interface AccountReconfiguration {
 
-       // Legal name associated with $username.
-       // When missing, the old name is kept.
-       name?: string;
+      // Addresses where to send the TAN for transactions.
+      // Currently only used for cashouts.
+      // If missing, cashouts will fail.
+      // In the future, might be used for other transactions
+      // as well.
+      challenge_contact_data?: ChallengeContactData;
 
-       // If present, change the is_exchange configuration.
-       // See `RegisterAccountRequest`
-       is_exchange?: boolean;
-     }
+      // 'payto' address pointing a bank account
+      // external to the bank.
+      // Payments will be sent to this bank account
+      // when the user wants to convert the local currency
+      // back to fiat currency outside the bank.
+      cashout_address?: string;
 
-   **Response:**
+      // Legal name associated with $username.
+      // When missing, the old name is kept.
+      name?: string;
 
-   :http:statuscode:`204 No content`:
-     Operation successful.
+      // If present, change the is_exchange configuration.
+      // See `RegisterAccountRequest`
+      is_exchange?: boolean;
+    }
 
-   :http:statuscode:`403 Forbidden`:
-     The rights to change ``$USERNAME`` are not sufficient.
-     That includes the case where a correctly authenticated
-     user tries to change their legal name.  It also
-     includes the case where 'admin' tries to change its
-     own account.
+  **Response:**
 
-   :http:statuscode:`404 Not found`:
-     The account pointed by ``$USERNAME``
-     was not found.
+  :http:statuscode:`204 No content`:
+    Operation successful.
+  :http:statuscode:`403 Forbidden`:
+    The rights to change ``$USERNAME`` are not sufficient.
+    That includes the case where a correctly authenticated
+    user tries to change their legal name.  It also
+    includes the case where 'admin' tries to change its
+    own account.
+  :http:statuscode:`404 Not found`:
+    The account pointed by ``$USERNAME`` was not found.
 
 
 .. _account-password-reconfig:
@@ -415,7 +413,7 @@ Account Management
     Credentials are valid but this user has no permission to the 
     the account info.
   :http:statuscode:`404 Not found`:
-    Username not found
+    The account pointed by ``$USERNAME`` was not found.
 
   **Details:**
 
@@ -448,9 +446,9 @@ Account Management
 Transactions
 ------------
 
-.. http:get:: ${BANK_API_BASE_URL}/accounts/${account_name}/transactions
+.. http:get:: ${BANK_API_BASE_URL}/accounts/${USERNAME}/transactions
 
-  Retrieve a subset of transactions related to $account_name.  Without
+  Retrieve a subset of transactions related to $USERNAME.  Without
   query parameters, it returns the last 5 transactions.
 
   The list of returned transactions is determined by a row ID *starting point*
@@ -485,9 +483,9 @@ Transactions
   :http:statuscode:`204 No content`:
     No transaction found.
   :http:statuscode:`401 Unauthorized`:
-    Invalid credentails
+    Invalid credentials
   :http:statuscode:`404 Not found`:
-    Username not found
+    The account pointed by ``$USERNAME`` was not found.
 
   **Details:**
 
@@ -497,7 +495,7 @@ Transactions
       transactions: BankAccountTransactionInfo[];
     }
 
-.. http:get:: ${BANK_API_BASE_URL}/accounts/${account_name}/transactions/${transaction_id}
+.. http:get:: ${BANK_API_BASE_URL}/accounts/${USERNAME}/transactions/${transaction_id}
 
   Retrieve the transaction whose identifier is ``transaction_id``.
 
@@ -506,7 +504,7 @@ Transactions
   :http:statuscode:`200 OK`:
     The bank responds with an `BankAccountTransactionInfo` object.
   :http:statuscode:`404 Not found`:
-    Username not found
+    The account pointed by ``$USERNAME`` was not found.
   :http:statuscode:`401 Unauthorized`:
     Invalid credentials.
 
@@ -529,9 +527,9 @@ Transactions
       date: Timestamp;
     }
 
-.. http:post:: ${BANK_API_BASE_URL}/accounts/${account_name}/transactions
+.. http:post:: ${BANK_API_BASE_URL}/accounts/${USERNAME}/transactions
 
-  Create a new transaction where the bank account with the label ``account_name`` is **debited**.
+  Create a new transaction where the bank account with the label ``USERNAME`` is **debited**.
 
   **Request:**
 
@@ -553,17 +551,23 @@ Transactions
   **Response:**
 
   :http:statuscode:`204 No content`:
-     the transaction has been created.
+    The transaction has been created.
   :http:statuscode:`400 Bad Request`:
-    the request was invalid or the payto://-URI used unacceptable features.
+    The request was invalid or the payto://-URI used unacceptable features.
   :http:statuscode:`401 Unauthorized`:
     Invalid credentials.
+  :http:statuscode:`404 Not found`:
+    The account pointed by ``$USERNAME`` was not found.
+  :http:statuscode:`409 Conflict`:
+    * ``TALER_EC_BANK_SAME_ACCOUNT`` : creditor account is the same than ``USERNAME``.
+    * ``TALER_EC_BANK_UNKNOWN_CREDITOR`` : creditor account was not found.
+    * ``TALER_EC_BANK_UNALLOWED_DEBIT`` : the account does not have sufficient funds.
 
 
 Taler Withdrawals
 -----------------
 
-.. http:post:: ${BANK_API_BASE_URL}/accounts/${account_name}/withdrawals
+.. http:post:: ${BANK_API_BASE_URL}/accounts/${USERNAME}/withdrawals
 
   Create a withdrawal operation, resulting in a ``taler://withdraw`` URI.
 
@@ -580,8 +584,10 @@ Taler Withdrawals
 
   :http:statuscode:`200 Ok`:
     The bank responds with an `BankAccountCreateWithdrawalResponse` object.
-  :http:statuscode:`403 Forbidden`:
-    The operation was rejected due to insufficient funds.
+  :http:statuscode:`404 Not found`:
+    The account pointed by ``$USERNAME`` was not found.
+  :http:statuscode:`409 Conflict`:
+    The account does not have sufficient funds.
 
   **Details:**
 
@@ -597,6 +603,39 @@ Taler Withdrawals
       taler_withdraw_uri: string;
     }
 
+.. http:post:: ${BANK_API_BASE_URL}/withdrawals/${withdrawal_id}/abort
+
+  Abort a withdrawal operation.  Has no effect on an already aborted
+  withdrawal operation.  Does not require further authentication as knowledge
+  of the withdrawal ID serves as an authenticator.
+
+  **Response:**
+
+  :http:statuscode:`204 No content`: 
+    The withdrawal operation has been aborted.
+  :http:statuscode:`404 Not found`:
+    The operation was not found
+  :http:statuscode:`409 Conflict`: 
+    The reserve operation has been confirmed previously and can't be aborted.
+
+.. http:post:: ${BANK_API_BASE_URL}/withdrawals/${withdrawal_id}/confirm
+
+  Confirm a withdrawal operation.  Has no effect on an already confirmed
+  withdrawal operation.  This call is responsible for wiring the funds to the
+  exchange.  Does not require further authentication as knowledge of the
+  withdrawal ID serves as an authenticator.
+
+  **Response:**
+
+  :http:statuscode:`204 No content`:
+    The withdrawal operation has been confirmed.
+  :http:statuscode:`404 Not found`:
+    The operation was not found
+  :http:statuscode:`409 Conflict`:
+    * ``TALER_EC_BANK_CONFIRM_ABORT_CONFLICT`` : the withdrawal has been aborted previously and can't be confirmed.
+    * ``TALER_EC_BANK_CONFIRM_INCOMPLETE`` : the withdraw operation cannot be confirmed because no exchange and reserve public key selection happened before.
+    * ``TALER_EC_BANK_UNALLOWED_DEBIT`` : the account does not have sufficient funds.
+
 .. http:get:: ${BANK_API_BASE_URL}/withdrawals/${withdrawal_id}
 
   Query the status of a withdrawal operation. Does not require further
@@ -638,37 +677,6 @@ Taler Withdrawals
       selected_exchange_account: string | null;
     }
 
-  
-
-.. http:post:: ${BANK_API_BASE_URL}/withdrawals/${withdrawal_id}/abort
-
-  Abort a withdrawal operation.  Has no effect on an already aborted
-  withdrawal operation.  Does not require further authentication as knowledge
-  of the withdrawal ID serves as an authenticator.
-
-  **Response:**
-
-  :http:statuscode:`204 No content`: 
-    The withdrawal operation has been aborted.
-  :http:statuscode:`409 Conflict`: 
-    The reserve operation has been confirmed previously and can't be aborted.
-
-.. http:post:: ${BANK_API_BASE_URL}/withdrawals/${withdrawal_id}/confirm
-
-  Confirm a withdrawal operation.  Has no effect on an already confirmed
-  withdrawal operation.  This call is responsible for wiring the funds to the
-  exchange.  Does not require further authentication as knowledge of the
-  withdrawal ID serves as an authenticator.
-
-  **Response:**
-
-  :http:statuscode:`204 No content`:
-     The withdrawal operation has been confirmed.
-  :http:statuscode:`409 Conflict`:
-     The withdrawal has been aborted previously and can't be confirmed.
-  :http:statuscode:`422 Unprocessable Entity` (New):
-     The withdraw operation cannot be confirmed because no exchange and reserve public key selection happened before.
-
 Cashouts
 --------
 
@@ -751,17 +759,16 @@ Cashouts
 
    **Response:**
 
-   :http:statuscode:`202 Accepted`:
-     The cashout request was correctly created and
-     the TAN authentication now is pending.
-     This returns the `CashoutPending` response.
-   :http:statuscode:`409 Conflict`:
-     The user did not share any contact data where to send the TAN,
-     the account does not have sufficient funds, or the
-     exchange rate was calculated incorrectly by the client.
-   :http:statuscode:`503 Service unavailable`:
-     The bank does not support the TAN channel for this operation.
-     The bank does not support cashout, client should check config response.
+  :http:statuscode:`202 Accepted`:
+    The cashout request was correctly created and
+    the TAN authentication now is pending.
+    This returns the `CashoutPending` response.
+  :http:statuscode:`404 Not found`:
+    The account pointed by ``$USERNAME`` was not found.
+  :http:statuscode:`409 Conflict`:
+    * ``TALER_EC_BANK_BAD_CONVERSION`` : exchange rate was calculated incorrectly by the client.
+    * ``TALER_EC_BANK_MISSING_TAN_INFO`` : the user did not share any contact data where to send the TAN with this channel.
+    * ``TALER_EC_BANK_UNALLOWED_DEBIT`` : the account does not have sufficient funds.
 
 
    **Details:**
@@ -848,7 +855,7 @@ Cashouts
   :http:statuscode:`204 No Content`:
     No cash-out operations were found at the bank
   :http:statuscode:`404 Not found`:
-    Username not fuond.
+    The account pointed by ``$USERNAME`` was not found.
   :http:statuscode:`503 Service unavailable`:
     This server does not support cashout, client should check config response.
 
@@ -1028,7 +1035,6 @@ Monitor
     * day
     * month
     * year
-    * decade
 
   :query which: *Optional*.
     This parameter points at a particular element of the *timeframe* parameter.
@@ -1039,7 +1045,6 @@ Monitor
     * day: from 1 to the last day of the current month.
     * month: from 1 to 12
     * year: Gregorian year in the YYYY format.
-    * decade: the least Y0 digits of a Gregorian year.  Banks should treat such decades as starting from the year 2000.  For example, if Y=2, this decade denotes the years 2020 to 2029.
 
   **Response:**