commit 3b73a5496fb6f7b614cf01e7b9f7fd3945f8baa4
parent 6e8685a96572b81693b7823943848090f31a6ad8
Author: Christian Grothoff <christian@grothoff.org>
Date: Fri, 3 Apr 2026 20:18:20 +0200
specify more error codes
Diffstat:
10 files changed, 130 insertions(+), 22 deletions(-)
diff --git a/core/exchange/post-auditors-AUDITOR_PUB-H_DENOM_PUB.rst b/core/exchange/post-auditors-AUDITOR_PUB-H_DENOM_PUB.rst
@@ -16,13 +16,20 @@
The backend has successfully stored the auditor signature.
:http:statuscode:`403 Forbidden`:
The auditor signature is invalid.
+ This response comes with a standard `ErrorDetail` response with
+ a code of ``TALER_EC_EXCHANGE_AUDITORS_AUDITOR_SIGNATURE_INVALID``.
:http:statuscode:`404 Not found`:
The denomination key for which the auditor is providing a signature is unknown.
The response will be a `DenominationUnknownMessage`.
:http:statuscode:`410 Gone`:
This auditor is no longer supported by the exchange.
+ This response comes with a standard `ErrorDetail` response with
+ a code of ``TALER_EC_EXCHANGE_AUDITORS_AUDITOR_INACTIVE``.
:http:statuscode:`412 Precondition failed`:
This auditor is not yet known to the exchange.
+ This response comes with a standard `ErrorDetail` response with
+ a code of ``TALER_EC_EXCHANGE_AUDITORS_AUDITOR_UNKNOWN``.
+ FIXME: probably should be changed to a 404!
:http:statuscode:`413 Request entity too large`:
The uploaded body is to long, it exceeds the size limit.
Returned with an error code of
diff --git a/core/exchange/post-batch-deposit.rst b/core/exchange/post-batch-deposit.rst
@@ -26,6 +26,9 @@
:http:statuscode:`403 Forbidden`:
One of the signatures is invalid.
This response comes with a standard `ErrorDetail` response.
+ Possible error codes include
+ ``TALER_EC_EXCHANGE_DEPOSIT_COIN_SIGNATURE_INVALID`` or
+ ``TALER_EC_EXCHANGE_DENOMINATION_SIGNATURE_INVALID``.
:http:statuscode:`404 Not found`:
Either one of the denomination keys is not recognized (expired or invalid),
or the wire type is not recognized.
@@ -46,11 +49,19 @@
can get from the exchange via the ``/coin/$COIN_PUB/history`` endpoint the record
of the transactions known for this coin's public key.
:http:statuscode:`410 Gone`:
- The requested denomination key is not yet or no longer valid.
- It either before the validity start, past the expiration or was revoked. The response is a
+ The requested denomination key is no longer valid.
+ It is past the expiration or was revoked. The response is a
`DenominationGoneMessage`. Clients must evaluate
the error code provided to understand which of the
cases this is and handle it accordingly.
+ Possible error codes include
+ ``TALER_EC_EXCHANGE_GENERIC_DENOMINATION_EXPIRED`` or
+ ``TALER_EC_EXCHANGE_GENERIC_DENOMINATION_REVOKED``.
+ :http:statuscode:`412 Precondition Failed`:
+ The requested denomination key is not yet valid.
+ It is before the validity start time. The response is a
+ `DenominationGoneMessage` with
+ ``TALER_EC_EXCHANGE_GENERIC_DENOMINATION_VALIDITY_IN_FUTURE``.
:http:statuscode:`413 Request entity too large`:
The uploaded body is to long, it exceeds the size limit.
Returned with an error code of
diff --git a/core/exchange/post-coins-COIN_PUB-refund.rst b/core/exchange/post-coins-COIN_PUB-refund.rst
@@ -30,6 +30,9 @@
The uploaded body is to long, it exceeds the size limit.
Returned with an error code of
``TALER_EC_GENERIC_UPLOAD_EXCEEDS_LIMIT``.
+ :http:statuscode:`424 Failed Dependency`:
+ A dependency of the refund operation failed.
+ This response comes with a standard `ErrorDetail` response.
**Details:**
diff --git a/core/exchange/post-melt.rst b/core/exchange/post-melt.rst
@@ -16,15 +16,27 @@
The request was successful. The response body is `MeltResponse` in this case.
:http:statuscode:`400 Bad Request`:
The request body is malformed or a parameter is invalid.
- This response comes with a standard `ErrorDetail` response with
- a code of ``TALER_EC_GENERIC_PARAMETER_MALFORMED``.
+ This response comes with a standard `ErrorDetail` response.
+ Possible error codes include ``TALER_EC_GENERIC_PARAMETER_MALFORMED``,
+ ``TALER_EC_EXCHANGE_GENERIC_CIPHER_MISMATCH``,
+ ``TALER_EC_EXCHANGE_MELT_COIN_EXPIRED_NO_ZOMBIE``,
+ ``TALER_EC_EXCHANGE_MELT_FEES_EXCEED_CONTRIBUTION``,
+ ``TALER_EC_EXCHANGE_REFRESHES_REVEAL_AGE_RESTRICTION_COMMITMENT_INVALID``, or
+ ``TALER_EC_EXCHANGE_REFRESHES_REVEAL_COST_CALCULATION_OVERFLOW``.
:http:statuscode:`403 Forbidden`:
One of the signatures is invalid.
+ This response comes with a standard `ErrorDetail` response.
+ Possible error codes include
+ ``TALER_EC_EXCHANGE_MELT_COIN_SIGNATURE_INVALID`` or
+ ``TALER_EC_EXCHANGE_DENOMINATION_SIGNATURE_INVALID``.
:http:statuscode:`404 Not found`:
The exchange does not recognize the denomination key as belonging to the exchange,
- or it has expired.
+ or the coin is unknown.
If the denomination key is unknown, the response will be
a `DenominationUnknownMessage`.
+ Possible error codes include
+ ``TALER_EC_EXCHANGE_GENERIC_DENOMINATION_KEY_UNKNOWN`` or
+ ``TALER_EC_EXCHANGE_GENERIC_COIN_UNKNOWN``.
:http:statuscode:`409 Conflict`:
The operation is not allowed as the coin has insufficient
residual value, or because the same public key of the coin has been
@@ -34,11 +46,23 @@
``TALER_EC_EXCHANGE_GENERIC_COIN_CONFLICTING_DENOMINATION_KEY``).
The response is `MeltForbiddenResponse` in both cases.
:http:statuscode:`410 Gone`:
- The requested denomination key is not yet or no longer valid.
- It either before the validity start, past the expiration or was revoked. The response is a
+ The requested denomination key is no longer valid.
+ It is past the expiration or was revoked. The response is a
`DenominationGoneMessage`. Clients must evaluate
the error code provided to understand which of the
cases this is and handle it accordingly.
+ Possible error codes include
+ ``TALER_EC_EXCHANGE_GENERIC_DENOMINATION_EXPIRED`` or
+ ``TALER_EC_EXCHANGE_GENERIC_DENOMINATION_REVOKED``.
+ :http:statuscode:`412 Precondition Failed`:
+ The requested denomination key is not yet valid.
+ It is before the validity start time. The response is a
+ `DenominationGoneMessage` with
+ ``TALER_EC_EXCHANGE_GENERIC_DENOMINATION_VALIDITY_IN_FUTURE``.
+ :http:statuscode:`503 Service Unavailable`:
+ The exchange currently has no signing keys available.
+ This response comes with a standard `ErrorDetail` response with
+ a code of ``TALER_EC_EXCHANGE_GENERIC_KEYS_MISSING``.
**Details:**
diff --git a/core/exchange/post-purses-PURSE_PUB-create.rst b/core/exchange/post-purses-PURSE_PUB-create.rst
@@ -22,6 +22,9 @@
:http:statuscode:`403 Forbidden`:
A coin, denomination or contract signature is invalid.
This response comes with a standard `ErrorDetail` response.
+ Possible error codes include
+ ``TALER_EC_EXCHANGE_PURSE_CREATE_SIGNATURE_INVALID`` or
+ ``TALER_EC_EXCHANGE_PURSE_ECONTRACT_SIGNATURE_INVALID``.
:http:statuscode:`404 Not Found`:
The denomination of one of the coins is unknown to the exchange.
:http:statuscode:`409 Conflict`:
@@ -49,6 +52,20 @@
The uploaded body is to long, it exceeds the size limit.
Returned with an error code of
``TALER_EC_GENERIC_UPLOAD_EXCEEDS_LIMIT``.
+ :http:statuscode:`425 Too Early`:
+ This response type is used if the given purse expiration time
+ is too far in the future (at least from the perspective
+ of the exchange). Thus, retrying at a later time may
+ succeed. The client should look at the ``Date:`` header
+ of the response to see if a minor time difference is to
+ blame and possibly adjust the request accordingly.
+ (Note: this status code is not yet used.)
+ :http:statuscode:`500 Internal Server Error`:
+ The exchange encountered an internal error.
+ This response comes with a standard `ErrorDetail` response.
+ Possible error codes include
+ ``TALER_EC_EXCHANGE_GENERIC_KEYS_MISSING`` or
+ ``TALER_EC_EXCHANGE_GENERIC_GLOBAL_FEES_MISSING``.
**Details:**
diff --git a/core/exchange/post-purses-PURSE_PUB-deposit.rst b/core/exchange/post-purses-PURSE_PUB-deposit.rst
@@ -21,7 +21,8 @@
This response comes with a standard `ErrorDetail` response.
:http:statuscode:`404 Not found`:
The purse is unknown.
- This response comes with a standard `ErrorDetail` response.
+ This response comes with a standard `ErrorDetail` response with
+ a code of ``TALER_EC_EXCHANGE_GENERIC_PURSE_UNKNOWN``.
:http:statuscode:`409 Conflict`:
The deposit operation has either failed because a coin has insufficient
residual value, or because the same public key of the coin has been
@@ -33,13 +34,16 @@
This response comes with a standard `PurseConflict` response
(alas some cases are impossible).
:http:statuscode:`410 Gone`:
- The purse has expired.
+ The purse has expired, was deleted, or the deposit was already decided.
+ Possible error codes include
+ ``TALER_EC_EXCHANGE_GENERIC_PURSE_EXPIRED``,
+ ``TALER_EC_EXCHANGE_GENERIC_PURSE_DELETED``, or
+ ``TALER_EC_EXCHANGE_PURSE_DEPOSIT_DECIDED_ALREADY``.
:http:statuscode:`413 Request entity too large`:
The uploaded body is to long, it exceeds the size limit.
Returned with an error code of
``TALER_EC_GENERIC_UPLOAD_EXCEEDS_LIMIT``.
-
**Details:**
.. ts:def:: PurseDeposits
diff --git a/core/exchange/post-purses-PURSE_PUB-merge.rst b/core/exchange/post-purses-PURSE_PUB-merge.rst
@@ -94,6 +94,9 @@
interface MergeConflict {
+ // Must be equal to TALER_EC_EXCHANGE_PURSE_MERGE_CONFLICTING_META_DATA
+ code: Integer;
+
// Client-side timestamp of when the merge request was made.
merge_timestamp: Timestamp;
diff --git a/core/exchange/post-recoup-refresh.rst b/core/exchange/post-recoup-refresh.rst
@@ -32,11 +32,18 @@
:http:statuscode:`403 Forbidden`:
The coin's signature is invalid.
This response comes with a standard `ErrorDetail` response.
+ Possible error codes include
+ ``TALER_EC_EXCHANGE_RECOUP_REFRESH_SIGNATURE_INVALID`` or
+ ``TALER_EC_EXCHANGE_DENOMINATION_SIGNATURE_INVALID``.
:http:statuscode:`404 Not found`:
- The denomination key is unknown, or the blinded
- coin is not known to have been withdrawn.
+ The denomination key is unknown, the blinded
+ coin is not known to have been withdrawn,
+ or the denomination is not eligible for recoup.
If the denomination key is unknown, the response will be
a `DenominationUnknownMessage`.
+ Possible error codes include
+ ``TALER_EC_EXCHANGE_RECOUP_REFRESH_MELT_NOT_FOUND`` or
+ ``TALER_EC_EXCHANGE_RECOUP_REFRESH_NOT_ELIGIBLE``.
:http:statuscode:`409 Conflict`:
The operation is not allowed as the coin has insufficient
residual value, or because the same public key of the coin has been
@@ -45,15 +52,27 @@
(usually ``TALER_EC_EXCHANGE_GENERIC_INSUFFICIENT_BALANCE``).
The response is a `DepositDoubleSpendError`.
:http:statuscode:`410 Gone`:
- The requested denomination key is not yet or no longer valid.
- It either before the validity start, past the expiration or was not yet revoked. The response is a
+ The requested denomination key is no longer valid.
+ It is past the expiration or was not yet revoked. The response is a
`DenominationGoneMessage`. Clients must evaluate
the error code provided to understand which of the
cases this is and handle it accordingly.
+ Possible error codes include
+ ``TALER_EC_EXCHANGE_GENERIC_DENOMINATION_EXPIRED``.
+ :http:statuscode:`412 Precondition Failed`:
+ The requested denomination key is not yet valid.
+ It is before the validity start time. The response is a
+ `DenominationGoneMessage` with
+ ``TALER_EC_EXCHANGE_GENERIC_DENOMINATION_VALIDITY_IN_FUTURE``.
:http:statuscode:`413 Request entity too large`:
The uploaded body is to long, it exceeds the size limit.
Returned with an error code of
``TALER_EC_GENERIC_UPLOAD_EXCEEDS_LIMIT``.
+ :http:statuscode:`500 Internal Server Error`:
+ The exchange encountered an internal error.
+ This response comes with a standard `ErrorDetail` response.
+ Possible error codes include
+ ``TALER_EC_EXCHANGE_RECOUP_REFRESH_BLINDING_FAILED``.
**Details:**
diff --git a/core/exchange/post-reserves-RESERVE_PUB-open.rst b/core/exchange/post-reserves-RESERVE_PUB-open.rst
@@ -19,15 +19,18 @@
the payment offered is insufficient for the requested operation.
:http:statuscode:`403 Forbidden`:
The *TALER_SIGNATURE_WALLET_RESERVE_OPEN* signature is invalid.
- This response comes with a standard `ErrorDetail` response.
+ This response comes with a standard `ErrorDetail` response with
+ a code of ``TALER_EC_EXCHANGE_RESERVES_OPEN_BAD_SIGNATURE``.
:http:statuscode:`404 Not found`:
The reserve key does not belong to a reserve known to the exchange.
+ This response comes with a standard `ErrorDetail` response with
+ a code of ``TALER_EC_EXCHANGE_GENERIC_RESERVE_UNKNOWN``.
:http:statuscode:`409 Conflict`:
The balance of the reserve or of a coin was insufficient.
Which case it is can be decided by looking at the error code
(``TALER_EC_EXCHANGE_GENERIC_INSUFFICIENT_FUNDS`` or
``TALER_EC_EXCHANGE_GENERIC_COIN_CONFLICTING_DENOMINATION_KEY`` or
- ``TALER_EC_EXCHANGE_OPEN_INSUFFICIENT_FUNDS``).
+ ``TALER_EC_EXCHANGE_RESERVES_OPEN_INSUFFICIENT_FUNDS``).
The specific fields of the response depend on the error code
and include the signatures (and what was signed over) proving the
conflict.
@@ -41,6 +44,12 @@
This account has not yet passed the KYC checks.
The client must pass KYC checks before the reserve can be opened.
The response will be an `LegitimizationNeededResponse` object.
+ :http:statuscode:`500 Internal Server Error`:
+ The exchange encountered an internal error.
+ This response comes with a standard `ErrorDetail` response.
+ Possible error codes include
+ ``TALER_EC_EXCHANGE_GENERIC_KEYS_MISSING`` or
+ ``TALER_EC_EXCHANGE_GENERIC_BAD_CONFIGURATION``.
**Details:**
diff --git a/core/exchange/post-withdraw.rst b/core/exchange/post-withdraw.rst
@@ -27,8 +27,10 @@
client can commit the coins signature to disk, the coins are not lost.
:http:statuscode:`400 Bad Request`:
The request body is malformed or a parameter is invalid.
- This response comes with a standard `ErrorDetail` response with
- a code of ``TALER_EC_GENERIC_PARAMETER_MALFORMED``.
+ This response comes with a standard `ErrorDetail` response.
+ Possible error codes include ``TALER_EC_GENERIC_PARAMETER_MALFORMED``,
+ ``TALER_EC_EXCHANGE_GENERIC_CIPHER_MISMATCH``, or
+ ``TALER_EC_EXCHANGE_WITHDRAW_IDEMPOTENT_PLANCHET``.
:http:statuscode:`403 Forbidden`:
A signature is invalid. This is usually the reserve signature.
This response comes with a standard `ErrorDetail` response with
@@ -72,13 +74,16 @@
3. The provided value for ``max_age`` is higher than the allowed value
according to the reserve's birthday. The response comes with a
standard `ErrorDetail` response with error-code
- ``TALER_EC_EXCHANGE_AGE_WITHDRAW_MAXIMUM_AGE_TOO_LARGE``
- and an additional field ``maximum_allowed_age`` for the maximum
+ ``TALER_EC_EXCHANGE_WITHDRAW_MAXIMUM_AGE_TOO_LARGE``
+ and additional fields ``allowed_maximum_age`` for the maximum
age (in years) that the client can commit to in a call
- to ``/withdraw``.
+ to ``/withdraw``, and ``reserve_birthday`` with the
+ reserve's birthday value.
4. The request uses a nonce value that was previously seen by
the exchange for a different request. As nonces must be unique,
- the request is rejected. This can only happen with some cipher
+ the request is rejected with
+ ``TALER_EC_EXCHANGE_WITHDRAW_NONCE_REUSE``.
+ This can only happen with some cipher
types that use nonces.
:http:statuscode:`410 Gone`:
A requested denomination key is no longer valid. There are two cases:
@@ -121,6 +126,12 @@
the withdraw amount threshold), as we need to create
a different payto://-URI for the KYC check depending
on the case.
+ :http:statuscode:`500 Internal Server Error`:
+ The exchange encountered an internal error during the withdrawal.
+ This response comes with a standard `ErrorDetail` response.
+ Possible error codes include
+ ``TALER_EC_EXCHANGE_WITHDRAW_AMOUNT_FEE_OVERFLOW`` or
+ ``TALER_EC_EXCHANGE_WITHDRAW_AMOUNT_OVERFLOW``.
:http:statuscode:`501 Not implemented`:
The client has provided a cipher that is not supported.
:http:statuscode:`502 Bad gateway`:
