commit 143efe7dbe36c5fb518a86c62283d0f69f206e31 parent 3b174f7eb00f78a6ffb0a246ffd593d4de26e0dc Author: Christian Grothoff <christian@grothoff.org> Date: Mon, 30 Mar 2026 17:13:13 +0200 document more HTTP status values and error codes returned Diffstat:
32 files changed, 189 insertions(+), 15 deletions(-)
diff --git a/core/exchange/get-aml-OFFICER_PUB-accounts.rst b/core/exchange/get-aml-OFFICER_PUB-accounts.rst @@ -52,6 +52,10 @@ The signature is invalid. :http:statuscode:`404 Not found`: The designated AML account is not known. + :http:statuscode:`406 Not Acceptable`: + The requested MIME type for the response is not supported. + This response comes with a standard `ErrorDetail` response with + a code of ``TALER_EC_GENERIC_PARAMETER_MALFORMED``. :http:statuscode:`409 Conflict`: The designated AML account is not enabled. diff --git a/core/exchange/get-aml-OFFICER_PUB-attributes-H_NORMALIZED_PAYTO.rst b/core/exchange/get-aml-OFFICER_PUB-attributes-H_NORMALIZED_PAYTO.rst @@ -37,6 +37,12 @@ The signature is invalid. :http:statuscode:`404 Not found`: The designated AML account is not known. + :http:statuscode:`400 Bad Request`: + The ``$H_NORMALIZED_PAYTO`` path segment is malformed. + This response comes with a standard `ErrorDetail` response with + a code of ``TALER_EC_GENERIC_PATH_SEGMENT_MALFORMED``. + :http:statuscode:`406 Not Acceptable`: + The requested MIME type for the response is not supported. :http:statuscode:`409 Conflict`: The designated AML account is not enabled. :http:statuscode:`501 Not implemented`: diff --git a/core/exchange/get-aml-OFFICER_PUB-kyc-statistics-NAMES.rst b/core/exchange/get-aml-OFFICER_PUB-kyc-statistics-NAMES.rst @@ -35,6 +35,14 @@ The responds will be an `AmlStatisticsResponse` message. :http:statuscode:`204 No content`: All the event counters are zero. + :http:statuscode:`404 Not found`: + The endpoint is unknown (e.g. extra path segments). + This response comes with a standard `ErrorDetail` response with + a code of ``TALER_EC_GENERIC_ENDPOINT_UNKNOWN``. + :http:statuscode:`414 URI Too Long`: + The statistics names string in the URL is too long. + This response comes with a standard `ErrorDetail` response with + a code of ``TALER_EC_GENERIC_URI_TOO_LONG``. **Details:** diff --git a/core/exchange/get-aml-OFFICER_PUB-legitimizations.rst b/core/exchange/get-aml-OFFICER_PUB-legitimizations.rst @@ -37,6 +37,12 @@ :http:statuscode:`200 Ok`: Information about possible measures is returned in a `LegitimizationMeasuresList` object. + :http:statuscode:`204 No content`: + There are no matching legitimization measures. + :http:statuscode:`404 Not found`: + The endpoint is unknown (e.g. extra path segments). + This response comes with a standard `ErrorDetail` response with + a code of ``TALER_EC_GENERIC_ENDPOINT_UNKNOWN``. **Details:** diff --git a/core/exchange/get-aml-OFFICER_PUB-measures.rst b/core/exchange/get-aml-OFFICER_PUB-measures.rst @@ -21,6 +21,10 @@ :http:statuscode:`200 Ok`: Information about possible measures is returned in a `AvailableMeasureSummary` object. + :http:statuscode:`404 Not found`: + The endpoint is unknown (e.g. extra path segments). + This response comes with a standard `ErrorDetail` response with + a code of ``TALER_EC_GENERIC_ENDPOINT_UNKNOWN``. **Details:** diff --git a/core/exchange/get-coins-COIN_PUB-history.rst b/core/exchange/get-coins-COIN_PUB-history.rst @@ -1 +1,29 @@ .. http:get:: /coins/$COIN_PUB/history + + Obtain the transaction history of a coin. + + **Request:** + + *Coin-History-Signature*: + The client must provide a Base-32 encoded EdDSA signature with + the coin's private key, affirming the desire to obtain the coin's + history. + + *If-None-Match*: + The client MAY provide an ``If-None-Match`` header with an ETag. + + **Response:** + + :http:statuscode:`200 OK`: + The coin is known to the exchange and the response is + the coin's transaction history. + :http:statuscode:`204 No content`: + The coin's transaction history is empty (but the ETag changed). + :http:statuscode:`403 Forbidden`: + The coin history signature is invalid. + This response comes with a standard `ErrorDetail` response with + a code of ``TALER_EC_EXCHANGE_COIN_HISTORY_BAD_SIGNATURE``. + :http:statuscode:`404 Not found`: + The coin is unknown to the exchange. + This response comes with a standard `ErrorDetail` response with + a code of ``TALER_EC_EXCHANGE_GENERIC_COIN_UNKNOWN``. diff --git a/core/exchange/get-contracts-CONTRACT_PUB.rst b/core/exchange/get-contracts-CONTRACT_PUB.rst @@ -6,6 +6,10 @@ :http:statuscode:`200 Ok`: The contract is being returned using a `ExchangeContractResponse`. + :http:statuscode:`400 Bad Request`: + The ``$CONTRACT_PUB`` is malformed. + This response comes with a standard `ErrorDetail` response with + a code of ``TALER_EC_EXCHANGE_CONTRACTS_INVALID_CONTRACT_PUB``. :http:statuscode:`404 Not found`: The contract is unknown. This response comes with a standard `ErrorDetail` response. diff --git a/core/exchange/get-keys.rst b/core/exchange/get-keys.rst @@ -13,6 +13,19 @@ The exchange responds with a `ExchangeKeysResponse` object. This request should virtually always be successful. It only fails if the exchange is misconfigured or has not yet been provisioned with key signatures via ``taler-exchange-offline``. + :http:statuscode:`400 Bad Request`: + A query parameter is malformed. + This response comes with a standard `ErrorDetail` response with + a code of ``TALER_EC_GENERIC_PARAMETER_MALFORMED``. + :http:statuscode:`502 Bad Gateway`: + A denomination or signing key helper is unavailable. + This response comes with a standard `ErrorDetail` response with + a code of ``TALER_EC_EXCHANGE_DENOMINATION_HELPER_UNAVAILABLE`` or + ``TALER_EC_EXCHANGE_SIGNKEY_HELPER_UNAVAILABLE``. + :http:statuscode:`503 Service Unavailable`: + The exchange has no valid denomination 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/get-kyc-check-H_NORMALIZED_PAYTO.rst b/core/exchange/get-kyc-check-H_NORMALIZED_PAYTO.rst @@ -74,6 +74,10 @@ :http:statuscode:`204 No content`: The exchange is not configured to perform KYC and thus the legal requirements are already satisfied. + :http:statuscode:`400 Bad Request`: + The ``$H_NORMALIZED_PAYTO`` path segment is malformed. + This response comes with a standard `ErrorDetail` response with + a code of ``TALER_EC_GENERIC_PATH_SEGMENT_MALFORMED``. :http:statuscode:`403 Forbidden`: The provided signature is not acceptable for the given account. The response will be an `KycCheckAccountExpectedResponse` object which specifies the expected account public key. :http:statuscode:`404 Not found`: diff --git a/core/exchange/get-kyc-info-ACCESS_TOKEN.rst b/core/exchange/get-kyc-info-ACCESS_TOKEN.rst @@ -41,6 +41,14 @@ the client might perform. :http:statuscode:`304 Not Modified`: The KYC requirements did not change. + :http:statuscode:`400 Bad Request`: + The ``$ACCESS_TOKEN`` is malformed. + This response comes with a standard `ErrorDetail` response with + a code of ``TALER_EC_GENERIC_PARAMETER_MALFORMED``. + :http:statuscode:`403 Forbidden`: + The access token is invalid or the account is not authorized. + This response comes with a standard `ErrorDetail` response with + a code of ``TALER_EC_EXCHANGE_KYC_INFO_AUTHORIZATION_FAILED``. **Details:** diff --git a/core/exchange/get-kyc-proof-PROVIDER_NAME.rst b/core/exchange/get-kyc-proof-PROVIDER_NAME.rst @@ -45,11 +45,18 @@ a Taler wallet, the response format is in human-readable HTML and not in machine-readable JSON. + :http:statuscode:`200 OK`: + The KYC process was not required. The response may contain + status information. :http:statuscode:`302 Found`: The KYC operation succeeded and the payment target is now authorized to transact. The browser is redirected to a human-readable page configured by the exchange operator. + :http:statuscode:`400 Bad Request`: + A query parameter is malformed. + This response comes with a standard `ErrorDetail` response with + a code of ``TALER_EC_GENERIC_PARAMETER_MALFORMED``. :http:statuscode:`401 Unauthorized`: The provided authorization token is invalid. :http:statuscode:`404 Not found`: diff --git a/core/exchange/get-purses-PURSE_PUB-merge.rst b/core/exchange/get-purses-PURSE_PUB-merge.rst @@ -22,6 +22,10 @@ The operation succeeded, the exchange provides details about the purse. The response will include a `PurseStatus` object. + :http:statuscode:`400 Bad Request`: + The ``$PURSE_PUB`` is malformed. + This response comes with a standard `ErrorDetail` response with + a code of ``TALER_EC_EXCHANGE_GENERIC_PURSE_PUB_MALFORMED``. :http:statuscode:`404 Not found`: The purse is unknown to the exchange. :http:statuscode:`410 Gone`: diff --git a/core/exchange/get-reserves-RESERVE_PUB.rst b/core/exchange/get-reserves-RESERVE_PUB.rst @@ -9,15 +9,15 @@ **Response:** :http:statuscode:`200 OK`: - The exchange responds with a `ReserveSummaryResponse` object; the reserve was known to the exchange. + The exchange responds with a `ReserveSummary` object; the reserve was known to the exchange. :http:statuscode:`404 Not found`: The reserve key does not belong to a reserve known to the exchange. **Details:** - .. ts:def:: ReserveSummaryResponse + .. ts:def:: ReserveSummary - interface ReserveSummaryResponse { + interface ReserveSummary { // Balance left in the reserve. balance: Amount; diff --git a/core/exchange/get-reserves-attest-RESERVE_PUB.rst b/core/exchange/get-reserves-attest-RESERVE_PUB.rst @@ -8,6 +8,10 @@ :http:statuscode:`200 OK`: The exchange responds with a `ReserveKycAttributes` object. + :http:statuscode:`400 Bad Request`: + The ``$RESERVE_PUB`` is malformed. + This response comes with a standard `ErrorDetail` response with + a code of ``TALER_EC_GENERIC_RESERVE_PUB_MALFORMED``. :http:statuscode:`404 Not found`: The reserve key does not belong to a reserve known to the exchange. :http:statuscode:`409 Conflict`: diff --git a/core/exchange/get-transfers-WTID.rst b/core/exchange/get-transfers-WTID.rst @@ -11,6 +11,10 @@ :http:statuscode:`200 OK`: The wire transfer is known to the exchange, details about it follow in the body. The body of the response is a `TrackTransferResponse`. + :http:statuscode:`400 Bad Request`: + The ``$WTID`` is malformed. + This response comes with a standard `ErrorDetail` response with + a code of ``TALER_EC_EXCHANGE_TRANSFERS_GET_WTID_MALFORMED``. :http:statuscode:`404 Not found`: The wire transfer identifier is unknown to the exchange. diff --git a/core/exchange/post-batch-deposit.rst b/core/exchange/post-batch-deposit.rst @@ -13,6 +13,16 @@ :http:statuscode:`200 OK`: The operation succeeded, the exchange confirms that no double-spending took place. The response will include a `DepositSuccess` object. + :http:statuscode:`400 Bad Request`: + The request is malformed or a parameter is invalid. + This response comes with a standard `ErrorDetail` response. + Possible error codes include ``TALER_EC_GENERIC_PARAMETER_MALFORMED``, + ``TALER_EC_EXCHANGE_DEPOSIT_NEGATIVE_VALUE_AFTER_FEE``, + ``TALER_EC_EXCHANGE_DEPOSIT_REFUND_DEADLINE_AFTER_WIRE_DEADLINE``, + ``TALER_EC_EXCHANGE_DEPOSIT_WIRE_DEADLINE_IS_NEVER``, + ``TALER_EC_EXCHANGE_GENERIC_AMOUNT_EXCEEDS_DENOMINATION_VALUE``, + ``TALER_EC_EXCHANGE_GENERIC_CIPHER_MISMATCH``, or + ``TALER_EC_EXCHANGE_DEPOSITS_POLICY_NOT_ACCEPTED``. :http:statuscode:`403 Forbidden`: One of the signatures is invalid. This response comes with a standard `ErrorDetail` response. diff --git a/core/exchange/post-blinding-prepare.rst b/core/exchange/post-blinding-prepare.rst @@ -16,6 +16,10 @@ `BlindingPrepareResponse`. Note that repeating exactly the same request will again yield the same response (assuming none of the denominations is expired). + :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``. :http:statuscode:`404 Not found`: A denomination key is not known to the exchange. The response is a `DenominationUnknownMessage`. diff --git a/core/exchange/post-kyc-start-ID.rst b/core/exchange/post-kyc-start-ID.rst @@ -17,8 +17,18 @@ :http:statuscode:`200 Ok`: The KYC process was successfully initiated. The URL is in a `KycProcessStartInformation` object. + :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``. :http:statuscode:`404 Not Found`: The ``$ID`` is unknown to the exchange. + :http:statuscode:`409 Conflict`: + The KYC form has already been uploaded or the KYC logic + is invalid. + This response comes with a standard `ErrorDetail` response with + a code of ``TALER_EC_EXCHANGE_KYC_FORM_ALREADY_UPLOADED`` or + ``TALER_EC_EXCHANGE_KYC_INVALID_LOGIC_TO_CHECK``. **Details:** diff --git a/core/exchange/post-kyc-upload-ID.rst b/core/exchange/post-kyc-upload-ID.rst @@ -21,6 +21,10 @@ :http:statuscode:`204 No Content`: The information was successfully uploaded. The SPA should fetch an updated ``/kyc-info/``. + :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``. :http:statuscode:`404 Not Found`: The ``$ID`` is unknown to the exchange. :http:statuscode:`409 Conflict`: diff --git a/core/exchange/post-management-keys.rst b/core/exchange/post-management-keys.rst @@ -16,6 +16,11 @@ A provided signature is invalid. :http:statuscode:`404 Not found`: One of the keys for which a signature was provided is unknown to the exchange. + :http:statuscode:`409 Conflict`: + The denomination or signing key meta data conflicts with existing keys. + This response comes with a standard `ErrorDetail` response with + a code of ``TALER_EC_EXCHANGE_MANAGEMENT_CONFLICTING_DENOMINATION_META_DATA`` + or ``TALER_EC_EXCHANGE_MANAGEMENT_CONFLICTING_SIGNKEY_META_DATA``. **Details:** diff --git a/core/exchange/post-management-wire.rst b/core/exchange/post-management-wire.rst @@ -10,6 +10,11 @@ :http:statuscode:`204 No content`: The wire method was successfully enabled. + :http:statuscode:`400 Bad Request`: + The payto URI or another parameter is malformed. + This response comes with a standard `ErrorDetail` response with + a code of ``TALER_EC_GENERIC_PAYTO_URI_MALFORMED`` or + ``TALER_EC_GENERIC_PARAMETER_MALFORMED``. :http:statuscode:`403 Forbidden`: The master signature is invalid. :http:statuscode:`409 Conflict`: diff --git a/core/exchange/post-melt.rst b/core/exchange/post-melt.rst @@ -14,6 +14,10 @@ :http:statuscode:`200 OK`: 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``. :http:statuscode:`403 Forbidden`: One of the signatures is invalid. :http:statuscode:`404 Not found`: diff --git a/core/exchange/post-purses-PURSE_PUB-create.rst b/core/exchange/post-purses-PURSE_PUB-create.rst @@ -12,6 +12,13 @@ The operation succeeded, the exchange confirms that all coins were deposited into the purse. The response will include a `PurseCreateSuccessResponse` object. + :http:statuscode:`400 Bad Request`: + The request is malformed or a parameter is invalid. + This response comes with a standard `ErrorDetail` response. + Possible error codes include ``TALER_EC_GENERIC_PARAMETER_MALFORMED``, + ``TALER_EC_EXCHANGE_PURSE_CREATE_EXPIRATION_BEFORE_NOW``, + ``TALER_EC_EXCHANGE_PURSE_CREATE_EXPIRATION_IS_NEVER``, or + ``TALER_EC_EXCHANGE_CREATE_PURSE_NEGATIVE_VALUE_AFTER_FEE``. :http:statuscode:`403 Forbidden`: A coin, denomination or contract signature is invalid. This response comes with a standard `ErrorDetail` response. diff --git a/core/exchange/post-purses-PURSE_PUB-deposit.rst b/core/exchange/post-purses-PURSE_PUB-deposit.rst @@ -12,6 +12,10 @@ The operation succeeded, the exchange confirms that all coins were deposited into the purse. The response will include a `PurseDepositSuccessResponse` object. + :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``. :http:statuscode:`403 Forbidden`: A coin or denomination signature is invalid. This response comes with a standard `ErrorDetail` response. diff --git a/core/exchange/post-purses-PURSE_PUB-merge.rst b/core/exchange/post-purses-PURSE_PUB-merge.rst @@ -13,6 +13,10 @@ The operation succeeded, the exchange confirms that the funds were merged into the account. The response will include a `MergeSuccess` object. + :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``. :http:statuscode:`402 Payment Required`: The purse is not yet full and more money needs to be deposited before the merge can be made. diff --git a/core/exchange/post-recoup-withdraw.rst b/core/exchange/post-recoup-withdraw.rst @@ -23,9 +23,7 @@ **Response:** :http:statuscode:`200 OK`: - The request was successful, and the response is - a `ReoupWithdrawResponse`. - FIXME: Does not really provide additional information. Maybe replace with a 204 instead? + The request was successful, and the response is a `ReserveSummary`. :http:statuscode:`403 Forbidden`: A coin's signature is invalid. This response comes with a standard `ErrorDetail` response. @@ -142,12 +140,3 @@ // created by this coin's private key. coin_sig: EddsaSignature; } - - .. ts:def:: RecoupWithdrawResponse - - interface RecoupWithdrawResponse { - // Public key of the reserve that will receive the recoup. - // Will be the same as the one from the original withdraw. - reserve_pub: EddsaPublicKey; - - } diff --git a/core/exchange/post-reserves-RESERVE_PUB-close.rst b/core/exchange/post-reserves-RESERVE_PUB-close.rst @@ -15,6 +15,10 @@ :http:statuscode:`200 OK`: The exchange responds with a `ReserveCloseResponse` object. + :http:statuscode:`400 Bad Request`: + The request timestamp has excessive clock skew. + This response comes with a standard `ErrorDetail` response with + a code of ``TALER_EC_EXCHANGE_GENERIC_CLOCK_SKEW``. :http:statuscode:`403 Forbidden`: The *TALER_SIGNATURE_WALLET_RESERVE_CLOSE* signature is invalid. This response comes with a standard `ErrorDetail` response. diff --git a/core/exchange/post-reserves-RESERVE_PUB-open.rst b/core/exchange/post-reserves-RESERVE_PUB-open.rst @@ -10,6 +10,10 @@ :http:statuscode:`200 OK`: The exchange responds with a `ReserveOpenResponse` object. + :http:statuscode:`400 Bad Request`: + The request timestamp has excessive clock skew. + This response comes with a standard `ErrorDetail` response with + a code of ``TALER_EC_EXCHANGE_GENERIC_CLOCK_SKEW``. :http:statuscode:`402 Payment Required`: The exchange responds with a `ReserveOpenFailure` object when the payment offered is insufficient for the requested operation. diff --git a/core/exchange/post-reserves-RESERVE_PUB-purse.rst b/core/exchange/post-reserves-RESERVE_PUB-purse.rst @@ -27,6 +27,10 @@ :http:statuscode:`404 Not found`: The purse creation operation failed as we could not find the reserve. This response comes with a standard `ErrorDetail` response. + :http:statuscode:`410 Gone`: + The purse has expired. + This response comes with a standard `ErrorDetail` response with + a code of ``TALER_EC_EXCHANGE_GENERIC_PURSE_EXPIRED``. :http:statuscode:`409 Conflict`: The purse creation failed because a purse with the same public key but different meta data was diff --git a/core/exchange/post-reserves-attest-RESERVE_PUB.rst b/core/exchange/post-reserves-attest-RESERVE_PUB.rst @@ -12,6 +12,10 @@ :http:statuscode:`200 OK`: The exchange responds with a `ReserveAttestResponse` object. + :http:statuscode:`400 Bad Request`: + The ``$RESERVE_PUB`` is malformed. + This response comes with a standard `ErrorDetail` response with + a code of ``TALER_EC_GENERIC_RESERVE_PUB_MALFORMED``. :http:statuscode:`403 Forbidden`: The *TALER_SIGNATURE_WALLET_KYC_DETAILS* signature is invalid. This response comes with a standard `ErrorDetail` response. diff --git a/core/exchange/post-reveal-melt.rst b/core/exchange/post-reveal-melt.rst @@ -16,6 +16,10 @@ :http:statuscode:`200 OK`: The coin's' secret material matched the commitment and the original request was well-formed. The response body is a `RevealResponse`. + :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``. :http:statuscode:`403 Forbidden`: One of the signatures is invalid. This response comes with a standard `ErrorDetail` response. diff --git a/core/exchange/post-withdraw.rst b/core/exchange/post-withdraw.rst @@ -25,6 +25,10 @@ Note that repeating exactly the same request will again yield the same response, so if the network goes down during the transaction or before the 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``. :http:statuscode:`403 Forbidden`: A signature is invalid. This is usually the reserve signature. This response comes with a standard `ErrorDetail` response with