commit 65feb2782cd5e9b5ec786a11bbcbae36df9bfbc7
parent 952f77852c8b1fdc92dc6530f9fd709d422623a3
Author: Christian Grothoff <christian@grothoff.org>
Date: Thu, 26 Mar 2026 22:52:18 +0100
clarify more status and error codes
Diffstat:
16 files changed, 144 insertions(+), 32 deletions(-)
diff --git a/core/merchant/delete-private-donau-DONAU_SERIAL.rst b/core/merchant/delete-private-donau-DONAU_SERIAL.rst
@@ -13,8 +13,11 @@
Returned with ``TALER_EC_GENERIC_PARAMETER_MALFORMED``.
:http:statuscode:`401 Unauthorized`:
The request is unauthorized.
+ Returned with ``TALER_EC_MERCHANT_GENERIC_UNAUTHORIZED``.
:http:statuscode:`404 Not found`:
- No such charity link exists.
+ No such instance or Donau charity link is known to the backend.
+ Returned with ``TALER_EC_MERCHANT_GENERIC_INSTANCE_UNKNOWN`` or
+ ``TALER_EC_MERCHANT_GENERIC_DONAU_UNKNOWN``.
:http:statuscode:`500 Internal Server Error`:
The server experienced an internal failure.
Returned with ``TALER_EC_GENERIC_DB_STORE_FAILED``.
diff --git a/core/merchant/delete-private-products-PRODUCT_ID.rst b/core/merchant/delete-private-products-PRODUCT_ID.rst
@@ -11,6 +11,7 @@
The backend has successfully deleted the product.
:http:statuscode:`401 Unauthorized`:
The request is unauthorized.
+ Returned with ``TALER_EC_MERCHANT_GENERIC_UNAUTHORIZED``.
:http:statuscode:`404 Not found`:
The backend does not know the instance or the product.
Returned with ``TALER_EC_MERCHANT_GENERIC_PRODUCT_UNKNOWN``.
diff --git a/core/merchant/delete-private-token.rst b/core/merchant/delete-private-token.rst
@@ -7,8 +7,14 @@
:http:statuscode:`204 No content`:
The access token used to authorize this request was revoked.
:http:statuscode:`400 Bad Request`:
- The authorization header token is malformed.
+ The request is malformed.
Returned with ``TALER_EC_GENERIC_PARAMETER_MALFORMED``.
+ :http:statuscode:`401 Unauthorized`:
+ The request is unauthorized.
+ Returned with ``TALER_EC_MERCHANT_GENERIC_UNAUTHORIZED``.
+ :http:statuscode:`404 Not found`:
+ The instance is unknown.
+ Returned with ``TALER_EC_MERCHANT_GENERIC_INSTANCE_UNKNOWN``.
:http:statuscode:`500 Internal Server Error`:
The server experienced an internal failure.
Returned with ``TALER_EC_GENERIC_DB_STORE_FAILED``.
diff --git a/core/merchant/delete-private-tokenfamilies-TOKEN_FAMILY_SLUG.rst b/core/merchant/delete-private-tokenfamilies-TOKEN_FAMILY_SLUG.rst
@@ -9,7 +9,6 @@
:http:statuscode:`204 No content`:
The backend has successfully deleted the token family.
-
:http:statuscode:`404 Not found`:
The merchant backend is unaware of the token family or instance.
:http:statuscode:`500 Internal Server Error`:
diff --git a/core/merchant/get-private-accounts.rst b/core/merchant/get-private-accounts.rst
@@ -8,9 +8,10 @@
**Response:**
:http:statuscode:`200 OK`:
- The backend has successfully returned all the accounts. Returns a `AccountsSummaryResponse`.
+ The backend has successfully returned all the accounts. Returns a `AccountsSummaryResponse`.
:http:statuscode:`404 Not found`:
- The backend has does not know about the instance.
+ The backend has does not know about the instance.
+ Returned with ``TALER_EC_MERCHANT_GENERIC_INSTANCE_UNKNOWN``.
:http:statuscode:`500 Internal Server Error`:
The server experienced an internal failure.
Returned with ``TALER_EC_GENERIC_DB_FETCH_FAILED``.
diff --git a/core/merchant/get-private-incoming-ID.rst b/core/merchant/get-private-incoming-ID.rst
@@ -15,11 +15,11 @@
The transfer ID parameter is malformed.
Returned with ``TALER_EC_GENERIC_PARAMETER_MALFORMED``.
:http:statuscode:`404 Not found`:
- The expected wire transfer ``$ID`` is unknown.
- :http:statuscode:`409 Conflict`:
- The exchange did not yet provide the transaction details
- (the ``last_http_status`` of the `ExpectedTransferDetails` is
- not 200). The information may be available later but is not yet.
+ The expected wire transfer ``$ID`` or instance is unknown.
+ Applicable error codes:
+
+ * ``TALER_EC_MERCHANT_GENERIC_INSTANCE_UNKNOWN``
+ * ``TALER_EC_MERCHANT_GENERIC_EXPECTED_TRANSFER_UNKNOWN``
:http:statuscode:`500 Internal Server Error`:
The server experienced an internal failure.
Returned with ``TALER_EC_GENERIC_DB_FETCH_FAILED``.
diff --git a/core/merchant/get-private-incoming.rst b/core/merchant/get-private-incoming.rst
@@ -27,6 +27,15 @@
:http:statuscode:`200 OK`:
The body of the response is a `ExpectedTransferListResponse`.
+ :http:statuscode:`400 Bad Request`:
+ The authorization header token is malformed.
+ Returned with ``TALER_EC_GENERIC_PARAMETER_MALFORMED``.
+ :http:statuscode:`401 Unauthorized`:
+ The request is unauthorized.
+ Returned with ``TALER_EC_MERCHANT_GENERIC_UNAUTHORIZED``.
+ :http:statuscode:`404 Not found`:
+ The instance is unknown.
+ Returned with ``TALER_EC_MERCHANT_GENERIC_INSTANCE_UNKNOWN``.
:http:statuscode:`500 Internal Server Error`:
The server experienced an internal failure.
Returned with ``TALER_EC_GENERIC_DB_FETCH_FAILED``.
diff --git a/core/merchant/get-private-kyc.rst b/core/merchant/get-private-kyc.rst
@@ -77,8 +77,10 @@
A query parameter is malformed.
:http:statuscode:`401 Unauthorized`:
The request is unauthorized.
+ Returned with ``TALER_EC_MERCHANT_GENERIC_UNAUTHORIZED``.
:http:statuscode:`404 Not found`:
The instance is unknown to the backend.
+ Returned with ``TALER_EC_MERCHANT_GENERIC_INSTANCE_UNKNOWN``.
:http:statuscode:`406 Not acceptable`:
The merchant backend could not produce a response in the desired format.
:http:statuscode:`503 Service unavailable`:
diff --git a/core/merchant/get-private-tokens.rst b/core/merchant/get-private-tokens.rst
@@ -19,10 +19,15 @@
Response is a `TokenInfos`.
:http:statuscode:`204 No content`:
No tokens.
+ :http:statuscode:`400 Bad Request`:
+ The request is malformed.
+ Returned with ``TALER_EC_GENERIC_PARAMETER_MALFORMED``.
:http:statuscode:`401 Unauthorized`:
Invalid or missing credentials.
- :http:statuscode:`403 Forbidden`:
- Missing rights.
+ Returned with ``TALER_EC_MERCHANT_GENERIC_UNAUTHORIZED``.
+ :http:statuscode:`404 Not found`:
+ The backend has does not know about the instance.
+ Returned with ``TALER_EC_MERCHANT_GENERIC_INSTANCE_UNKNOWN``.
:http:statuscode:`500 Internal Server Error`:
The server experienced an internal failure.
Returned with ``TALER_EC_GENERIC_DB_FETCH_FAILED``.
diff --git a/core/merchant/post-challenge-CHALLENGE_ID-confirm.rst b/core/merchant/post-challenge-CHALLENGE_ID-confirm.rst
@@ -17,13 +17,7 @@
**Request:**
- .. ts:def:: MerchantChallengeSolveRequest
-
- interface MerchantChallengeSolveRequest {
-
- // The TAN code that solves $CHALLENGE_ID.
- tan: string;
- }
+ The request body must be a `MerchantChallengeSolveRequest`.
**Response:**
@@ -34,10 +28,40 @@
Returned with ``TALER_EC_MERCHANT_TAN_CHALLENGE_UNKNOWN``.
:http:statuscode:`409 Conflict`:
Wrong TAN, returned with an
- error code of ``TALER_EC_MERCHANT_TAN_CHALLENGE_FAILED``.
+ error code of ``TALER_EC_MERCHANT_TAN_CHALLENGE_FAILED``
+ in a response of type `MerchantChallengeFailedResponse`.
:http:statuscode:`429 Too many requests`:
Too many failed confirmation attempts, a new TAN must be requested.
Returned with ``TALER_EC_MERCHANT_TAN_TOO_MANY_ATTEMPTS``.
:http:statuscode:`500 Internal Server Error`:
The server experienced an internal failure.
Returned with ``TALER_EC_GENERIC_DB_STORE_FAILED``.
+
+ **Details:**
+
+ .. ts:def:: MerchantChallengeSolveRequest
+
+ interface MerchantChallengeSolveRequest {
+
+ // The TAN code that solves $CHALLENGE_ID.
+ tan: string;
+ }
+
+ .. ts:def:: MerchantChallengeFailedResponse
+
+ interface MerchantChallengeFailedResponse {
+
+ // Numeric `error code <error-codes>` unique to the condition.
+ // The other arguments are specific to the error value reported here.
+ code: ErrorCode;
+
+ // Human-readable description of the error, i.e. "missing parameter", "commitment violation", ...
+ // Should give a human-readable hint about the error's nature. Optional, may change without notice!
+ hint?: string;
+
+ // Optional detail about the specific input value that failed. May change without notice!
+ detail?: string;
+
+ // Counter with the number of attempts left.
+ retry_counter: Integer;
+ }
diff --git a/core/merchant/post-instances-INSTANCE-forgot-password.rst b/core/merchant/post-instances-INSTANCE-forgot-password.rst
@@ -21,8 +21,6 @@
the `ChallengeResponse`. @since **v21**
:http:statuscode:`204 No content`:
The backend has successfully changed the credentials for the instance.
- :http:statuscode:`401 Unauthorized`:
- The request is unauthorized.
:http:statuscode:`403 Forbidden`:
MFA channels are not available for this instance.
Returned with ``TALER_EC_MERCHANT_GENERIC_MFA_MISSING``.
diff --git a/core/merchant/post-management-instances.rst b/core/merchant/post-management-instances.rst
@@ -7,10 +7,13 @@
**Request:**
- The request must be a `InstanceConfigurationMessage`.
+ The request must be a `InstanceConfigurationRequest`.
**Response:**
+ :http:statuscode:`200 Ok`:
+ An instance has been created and a login token is being returned.
+ The response body will be a `InstanceCreatedResponse`
:http:statuscode:`202 Accepted`:
2FA is required for this operation, usually to validate the
email and/or phone numbers registered for the instance.
@@ -33,9 +36,9 @@
**Details:**
- .. ts:def:: InstanceConfigurationMessage
+ .. ts:def:: InstanceConfigurationRequest
- interface InstanceConfigurationMessage {
+ interface InstanceConfigurationRequest {
// Name of the merchant instance to create (will become $INSTANCE).
// Must match the regex ``^[A-Za-z0-9][A-Za-z0-9_.@-]+$``.
@@ -99,3 +102,29 @@
// @since **v22**, defaults to no rounding if not given.
default_wire_transfer_rounding_interval?: RoundingInterval;
}
+
+ .. ts:def:: InstanceCreatedResponse
+
+ interface InstanceCreatedResponse {
+
+ // The login token that can be used to access resources
+ // that are in scope for some time. Must be prefixed
+ // with "Bearer " when used in the "Authorization" HTTP header.
+ // Will already begin with the RFC 8959 prefix.
+ // **Since v19**
+ access_token: string;
+
+ // Legacy field for the access token.
+ // @deprecated since **v19**.
+ token: string;
+
+ // Scope of the access token
+ scope: "readonly" | "write" | "all" | "order-simple" | "order-pos" | "order-mgmt" | "order-full";
+
+ // True if the access token can be refreshed.
+ refreshable: boolean;
+
+ // Time when the access token expires.
+ expiration: Timestamp;
+
+ }
diff --git a/core/merchant/post-orders-ORDER_ID-paid.rst b/core/merchant/post-orders-ORDER_ID-paid.rst
@@ -24,11 +24,16 @@
Either the client request is malformed or some specific processing error
happened that may be the fault of the client as detailed in the JSON body
of the response.
+ Returned with ``TALER_EC_GENERIC_PARAMETER_MALFORMED``.
:http:statuscode:`403 Forbidden`:
The signature was not valid.
+ Returned with ``TALER_EC_MERCHANT_POST_ORDERS_ID_PAID_COIN_SIGNATURE_INVALID``.
:http:statuscode:`404 Not found`:
The merchant backend could not find the order or the instance
and thus cannot process the request.
+ Returned with ``TALER_EC_MERCHANT_GENERIC_INSTANCE_UNKNOWN`` or
+ ``TALER_EC_MERCHANT_GENERIC_ORDER_UNKNOWN``.
+ :http:statuscode:`404 Not found`:
**Details**:
diff --git a/core/merchant/post-orders-ORDER_ID-refund.rst b/core/merchant/post-orders-ORDER_ID-refund.rst
@@ -12,11 +12,19 @@
:http:statuscode:`200 OK`:
The response is a `WalletRefundResponse`.
:http:statuscode:`204 No content`:
- There are no refunds for the order.
+ There are no refunds possible for the order. Should
+ mean that the order was paid, but the total was zero,
+ hence refunds are not possible.
:http:statuscode:`403 Forbidden`:
The ``h_contract`` does not match the order.
+ Returned with ``TALER_EC_MERCHANT_GENERIC_CONTRACT_HASH_DOES_NOT_MATCH_ORDER``.
:http:statuscode:`404 Not found`:
- The merchant backend is unaware of the order.
+ The merchant backend is unaware of the instance or order.
+
+ Applicable error codes:
+ * ``MERCHANT_GENERIC_ORDER_UNKNOWN``
+ * ``MERCHANT_GENERIC_INSTANCE_UNKNOWN``
+
:http:statuscode:`410 Gone`:
The wire deadline has past and it is too late to grant a refund.
Since protocol **v24**.
diff --git a/core/merchant/post-orders-ORDER_ID-unclaim.rst b/core/merchant/post-orders-ORDER_ID-unclaim.rst
@@ -15,12 +15,28 @@
:http:statuscode:`204 No content`:
The client has successfully unclaimed the order.
+ :http:statuscode:`400 Bad request`:
+ The request is malformed. Returned with
+ ``TALER_EC_GENERIC_PARAMETER_MALFORMED``.
:http:statuscode:`403 Forbidden`:
- The signature is invalid.
+ The provided unclaim signature is invalid.
+ Returned with ``TALER_EC_MERCHANT_POST_ORDERS_UNCLAIM_SIGNATURE_INVALID``.
:http:statuscode:`404 Not found`:
- The backend is unaware of the instance or order.
- :http:statuscode:`409 Conflict`:
- The order was already paid, and thus cannot be unclaimed anymore.
+ The backend is unaware of the instance or claimed order.
+
+ Applicable error codes:
+ * ``TALER_EC_MERCHANT_GENERIC_INSTANCE_UNKNOWN``
+ * ``TALER_EC_MERCHANT_POST_ORDERS_ID_CLAIM_NOT_FOUND``
+
+ The latter includes cases where the order was already
+ paid as well as cases where the order does not exist or
+ was simply not claimed.
+
+ :http:statuscode:`500 Internal Server Error`:
+ The server experienced an internal failure.
+ Returned with ``TALER_EC_GENERIC_DB_COMMIT_FAILED`` or
+ ``TALER_EC_GENERIC_DB_SOFT_FAILURE``.
+
**Details:**
diff --git a/core/merchant/post-reports-REPORT_ID.rst b/core/merchant/post-reports-REPORT_ID.rst
@@ -15,9 +15,15 @@
The backend has successfully added a new report.
Details returned (including the content type) depend
fully on the type of report that was requested.
-
+ :http:statuscode:`400 Bad request`:
+ Malformed JSON or missing fields.
+ Returned with ``TALER_EC_GENERIC_PARAMETER_MALFORMED``.
:http:statuscode:`404 Not found`:
The report ID *or* the report token are unknown.
+ Returned with ``TALER_EC_MERCHANT_GENERIC_REPORT_UNKNOWN``.
+ :http:statuscode:`500 Internal Server Error`:
+ The server experienced an internal failure.
+ Returned with ``TALER_EC_GENERIC_DB_FETCH_FAILED``.
**Details:**
