commit 567af687099de4fee506a673ed4ea575149270d6
parent 756089cf3deeb6b3e197164d54a1990d2c44a371
Author: Christian Grothoff <grothoff@gnunet.org>
Date: Mon, 26 Jan 2026 06:18:30 +0100
document specific EC codes better
Diffstat:
1 file changed, 39 insertions(+), 4 deletions(-)
diff --git a/core/api-merchant.rst b/core/api-merchant.rst
@@ -611,7 +611,6 @@ Making the payment
This includes the case where the payment is insufficient (sum is below
the required total amount, for example because the wallet calculated the
fees wrong).
-
Applicable error codes:
* ``MERCHANT_POST_ORDERS_ID_PAY_DENOMINATION_KEY_NOT_FOUND``: Wallet tried
@@ -624,10 +623,24 @@ Making the payment
:http:statuscode:`403 Forbidden`:
One of the coin signatures was not valid.
:http:statuscode:`404 Not found`:
- The merchant backend could not find the order or the instance and thus cannot process the payment.
+ The merchant backend could not find the order
+ or the instance or a token family or
+ the Donau charity specified in
+ the contract and thus cannot process the payment.
+ Applicable error codes:
+
+ * ``MERCHANT_GENERIC_TOKEN_KEY_UNKNOWN``
+ * ``MERCHANT_GENERIC_ORDER_UNKNOWN``
+ * ``MERCHANT_GENERIC_DONAU_CHARITY_UNKNOWN``
+ * ``MERCHANT_GENERIC_INSTANCE_UNKNOWN``
+
:http:statuscode:`408 Request timeout`:
The backend took too long to process the request. Likely the merchant's connection
to the exchange timed out. Try again.
+ Applicable error codes:
+
+ * ``MERCHANT_GENERIC_EXCHANGE_TIMEOUT``
+
:http:statuscode:`409 Conflict`:
The exchange rejected the payment because a coin was already spent (or
used in a different way for the same purchase previously), or
@@ -636,14 +649,19 @@ Making the payment
(this includes re-using the same coin after a refund),
the response will include the ``exchange_url`` for which the payment failed,
in addition to the response from the exchange to the ``/batch-deposit`` request.
-
Applicable error codes:
* ``MERCHANT_POST_ORDERS_ID_PAY_INSUFFICIENT_FUNDS``: Exchange reported insufficient
funds for one of the coins.
:http:statuscode:`410 Gone`:
- The offer has expired and is no longer available.
+ The offer has expired and is no longer available or
+ the provided payment has expired.
+ Applicable error codes:
+
+ * ``MERCHANT_POST_ORDERS_ID_PAY_DENOMINATION_DEPOSIT_EXPIRED``: payment expired
+ * ``MERCHANT_POST_ORDERS_ID_PAY_OFFER_EXPIRED``: offer expired
+
:http:statuscode:`412 Precondition failed`:
The given exchange is not acceptable for this merchant, as it is not in the
list of accepted exchanges and not audited by an approved auditor.
@@ -660,11 +678,28 @@ Making the payment
The body is a `PaymentDeniedLegallyResponse` with
details about the failure.
Since protocol **v17**.
+ :http:statuscode:`501 Not implemented`:
+ This is returned if an optional feature required to
+ process this particular payment is no longer implemented.
+ This should only be possible if a different version
+ of the backend software was deployed between order
+ creation and payment.
+
+ Applicable error codes:
+
+ * ``MERCHANT_GENERIC_DONAU_NOT_CONFIGURED``: returned if donations are not supported
+ * ``MERCHANT_GENERIC_FEATURE_NOT_AVAILABLE``: usually returned if a token type is not supported
+
:http:statuscode:`502 Bad gateway`:
The merchant's interaction with the exchange failed in some way.
The client might want to try again later.
This includes failures such as the denomination key of a coin not being
known to the exchange as far as the merchant can tell.
+ Applicable error codes:
+
+ * ``MERCHANT_GENERIC_EXCHANGE_UNEXPECTED_STATUS``
+ * ``MERCHANT_GENERIC_EXCHANGE_REPLY_MALFORMED``
+
:http:statuscode:`504 Gateway timeout`:
The merchant's interaction with the exchange took too long.
The client might want to try again later.
