commit 74597ed06bcdf8b3b1a99e277d08106b7199fa41
parent 4e1594c055200bc29cc5eed36addd719f1c06154
Author: Christian Grothoff <christian@grothoff.org>
Date: Wed, 8 Apr 2026 03:20:09 +0200
document donau EC codes properly
Diffstat:
10 files changed, 137 insertions(+), 50 deletions(-)
diff --git a/core/donau/delete-charities-CHARITY_ID.rst b/core/donau/delete-charities-CHARITY_ID.rst
@@ -6,8 +6,14 @@
**Response:**
- :http:statuscode:`204 No content`:
- The request was successful.
-
+ :http:statuscode:`204 No Content`:
+ The request was successful and the charity has been deleted.
+ :http:statuscode:`400 Bad Request`:
+ The ``charity_id`` in the URL could not be parsed.
+ Returned with error code ``TALER_EC_GENERIC_PARAMETER_MALFORMED``.
:http:statuscode:`403 Forbidden`:
- The request did not contain an accepted administrator bearer token in it's header.
+ The request did not contain an accepted administrator bearer token in its header.
+ Returned with error code ``TALER_EC_GENERIC_TOKEN_PERMISSION_INSUFFICIENT``.
+ :http:statuscode:`500 Internal Server Error`:
+ The Donau encountered an internal database error.
+ Returned with error code ``TALER_EC_GENERIC_DB_FETCH_FAILED``.
diff --git a/core/donau/get-charities.rst b/core/donau/get-charities.rst
@@ -6,10 +6,18 @@
**Request:**
- **Reponse:**
+ **Response:**
:http:statuscode:`200 OK`:
The request was successful, and the response is a `Charities`.
+ :http:statuscode:`204 No Content`:
+ No charities are registered at this time.
+ :http:statuscode:`403 Forbidden`:
+ The request did not contain an accepted administrator bearer token in its header.
+ Returned with error code ``TALER_EC_GENERIC_TOKEN_PERMISSION_INSUFFICIENT``.
+ :http:statuscode:`500 Internal Server Error`:
+ The Donau encountered an internal database error.
+ Returned with error code ``TALER_EC_GENERIC_DB_FETCH_FAILED``.
**Details:**
diff --git a/core/donau/get-charity-CHARITY_ID.rst b/core/donau/get-charity-CHARITY_ID.rst
@@ -18,9 +18,21 @@
**Response:**
:http:statuscode:`200 OK`:
- The Donau responds with a `Charity` object
- :http:statuscode:`404 Not found`:
- The charity id does not belong to a charity known to the Donau.
+ The Donau responds with a `Charity` object.
+ :http:statuscode:`400 Bad Request`:
+ The ``$CHARITY_ID`` is malformed or the required ``Charity-Signature`` header
+ is missing or cannot be parsed.
+ Returned with error code ``TALER_EC_GENERIC_PARAMETER_MALFORMED`` or
+ ``TALER_EC_GENERIC_PARAMETER_MISSING``.
+ :http:statuscode:`403 Forbidden`:
+ The charity signature provided in the ``Charity-Signature`` header is invalid.
+ Returned with error code ``TALER_EC_GENERIC_FORBIDDEN``.
+ :http:statuscode:`404 Not Found`:
+ The charity ID does not belong to a charity known to the Donau.
+ Returned with error code ``TALER_EC_DONAU_CHARITY_NOT_FOUND``.
+ :http:statuscode:`500 Internal Server Error`:
+ The Donau encountered an internal database error.
+ Returned with error code ``TALER_EC_GENERIC_DB_FETCH_FAILED``.
.. ts:def:: Charity
diff --git a/core/donau/get-donation-statement-YEAR-HASH_DONOR_ID.rst b/core/donau/get-donation-statement-YEAR-HASH_DONOR_ID.rst
@@ -8,11 +8,21 @@
:http:statuscode:`200 OK`:
The request was successful, and the response is a `DonationStatementResponse`.
- :http:statuscode:`403 Forbidden`:
- One of the signatures is invalid. This response comes with a standard `ErrorDetail` response.
- :http:statuscode:`404 Not found`:
- Either the donor or the year or the corresponding donation statement was not found.
- This response comes with a standard `ErrorDetail` response.
+ :http:statuscode:`204 No Content`:
+ No donation statement exists for the given year and donor.
+ :http:statuscode:`400 Bad Request`:
+ The ``$YEAR`` or ``$HASH_DONOR_ID`` in the URL is malformed.
+ Returned with error code ``TALER_EC_GENERIC_PARAMETER_MALFORMED``.
+ :http:statuscode:`500 Internal Server Error`:
+ The Donau encountered an internal error, such as a database failure or
+ signing key unavailability.
+ Returned with error code ``TALER_EC_GENERIC_DB_FETCH_FAILED``,
+ ``TALER_EC_DONAU_GENERIC_KEYS_MISSING``, or
+ ``TALER_EC_DONAU_SIGNKEY_HELPER_BUG``.
+ :http:statuscode:`503 Service unavailable`:
+ The donau is lacking the keys to create the donation statement.
+ Returned with error code
+ ``TALER_EC_DONAU_GENERIC_KEYS_MISSING``.
**Details:**
diff --git a/core/donau/get-keys.rst b/core/donau/get-keys.rst
@@ -10,6 +10,15 @@
:http:statuscode:`200 OK`:
The Donau responds with a `DonauKeysResponse` object. This request should
virtually always be successful. It only fails if the Donau is misconfigured.
+ :http:statuscode:`502 Bad Gateway`:
+ The Donau is unable to reach one of its cryptographic helper processes.
+ Returned with error code
+ ``TALER_EC_DONAU_DONATION_UNIT_HELPER_UNAVAILABLE`` or
+ ``TALER_EC_DONAU_SIGNKEY_HELPER_UNAVAILABLE``.
+ :http:statuscode:`503 Service Unavailable`:
+ The Donau has no valid keys at this time, likely due to a configuration
+ problem.
+ Returned with error code ``TALER_EC_DONAU_GENERIC_KEYS_MISSING``.
**Details:**
diff --git a/core/donau/patch-charities-CHARITY_ID.rst b/core/donau/patch-charities-CHARITY_ID.rst
@@ -9,19 +9,23 @@
:http:statuscode:`200 OK`:
The update succeeded. The response body is empty.
-
:http:statuscode:`400 Bad Request`:
- The request was malformed. For example, ``max_per_year`` must not be
+ The request was malformed. For example, the ``charity_id`` in the URL could
+ not be parsed, required JSON fields are missing, or ``max_per_year`` is
smaller than the current ``receipts_to_date`` of the charity.
-
- :http:statuscode:`401 Unauthorized`:
- Missing or invalid bearer token.
-
+ Returned with error code ``TALER_EC_GENERIC_PARAMETER_MALFORMED`` or
+ ``TALER_EC_GENERIC_JSON_INVALID``.
:http:statuscode:`403 Forbidden`:
The request did not contain an accepted administrator bearer token in its header.
-
+ Returned with error code ``TALER_EC_GENERIC_TOKEN_PERMISSION_INSUFFICIENT``.
:http:statuscode:`404 Not Found`:
The charity ID is unknown to the Donau.
+ Returned with error code ``TALER_EC_DONAU_CHARITY_NOT_FOUND``.
+ :http:statuscode:`500 Internal Server Error`:
+ The Donau encountered an internal database error.
+ Returned with error code ``TALER_EC_GENERIC_DB_FETCH_FAILED``,
+ ``TALER_EC_GENERIC_DB_STORE_FAILED``, or
+ ``TALER_EC_GENERIC_INTERNAL_INVARIANT_FAILURE``.
**Details:**
diff --git a/core/donau/post-batch-issue-CHARITY_ID.rst b/core/donau/post-batch-issue-CHARITY_ID.rst
@@ -8,18 +8,31 @@
:http:statuscode:`200 OK`:
The request was successful, and the response is a `BlindedDonationReceiptSignaturesResponse`.
+ Also returned for idempotent re-requests of an already-processed batch.
+ :http:statuscode:`400 Bad Request`:
+ The request was malformed. This can occur when the ``$CHARITY_ID`` cannot be
+ parsed, the ``budikeypairs`` array is empty or contains malformed entries,
+ or the total donation amount exceeds the charity's per-year limit.
+ Returned with error code ``TALER_EC_GENERIC_PARAMETER_MALFORMED``,
+ ``TALER_EC_GENERIC_JSON_INVALID``, or
+ ``TALER_EC_DONAU_EXCEEDING_DONATION_LIMIT``.
:http:statuscode:`403 Forbidden`:
- The charity signature is invalid. This response comes with a standard `ErrorDetail` response.
- :http:statuscode:`404 Not found`:
- At least one of the donation unit keys is not known to the Donau. Comes with a `DonationUnitUnknownError`.
- This suggests a bug in the donor as it should have used current donation unit keys from :ref:`/keys<donau_status>`.
- :http:statuscode:`409 Conflict`:
- The donation volume of the charity is not sufficient to issue donation receipts for all sent in blinded udis.
- The response is a `IssueError` object.
- :http:statuscode:`410 Gone`:
- The requested donation unit key is not yet or no longer valid. It either before the validity year, past the
- year or was revoked. The response is a `DonationUnitExpiredMessage`. Clients must evaluate the error code
- provided to understand which of the cases this is and handle it accordingly.
+ The charity signature is invalid.
+ Returned with error code ``TALER_EC_DONAU_CHARITY_SIGNATURE_INVALID``.
+ :http:statuscode:`404 Not Found`:
+ The charity is unknown to the Donau, or at least one of the referenced
+ donation unit keys could not be found.
+ Returned with error code ``TALER_EC_DONAU_CHARITY_NOT_FOUND`` or
+ ``TALER_EC_DONAU_GENERIC_DONATION_UNIT_UNKNOWN``.
+ :http:statuscode:`500 Internal Server Error`:
+ The Donau encountered an internal error, such as a database failure or
+ a signing helper problem.
+ Returned with error code ``TALER_EC_GENERIC_DB_FETCH_FAILED`` or
+ ``TALER_EC_GENERIC_INTERNAL_INVARIANT_FAILURE``
+ :http:statuscode:`503 Service unavailable`:
+ The donau is lacking the keys to create the donation statement.
+ Returned with error code
+ ``TALER_EC_DONAU_GENERIC_KEYS_MISSING``.
**Details:**
diff --git a/core/donau/post-batch-submit.rst b/core/donau/post-batch-submit.rst
@@ -10,10 +10,23 @@
:http:statuscode:`201 Created`:
The request was successful, and a donation statement is now available. The response will be empty.
+ :http:statuscode:`400 Bad Request`:
+ The request body is malformed, required fields are missing, or the
+ ``donation_receipts`` array is empty or contains malformed entries.
+ Returned with error code ``TALER_EC_GENERIC_JSON_INVALID`` or
+ ``TALER_EC_GENERIC_PARAMETER_MALFORMED``.
:http:statuscode:`403 Forbidden`:
- One of the signatures is invalid. This response comes with a standard `ErrorDetail` response.
- :http:statuscode:`404 Not found`:
- At least one of the donation unit keys is not known to the Donau. Comes with a `DonationUnitUnknownError`.
+ One of the donation receipt signatures is invalid.
+ Returned with error code ``TALER_EC_DONAU_DONATION_RECEIPT_SIGNATURE_INVALID``.
+ :http:statuscode:`404 Not Found`:
+ At least one of the donation unit keys is not known to the Donau.
+ Returned with error code ``TALER_EC_DONAU_GENERIC_DONATION_UNIT_UNKNOWN``.
+ :http:statuscode:`409 Conflict`:
+ A duplicate donor identifier nonce was detected within the submitted receipts.
+ Returned with error code ``TALER_EC_DONAU_DONOR_IDENTIFIER_NONCE_REUSE``.
+ :http:statuscode:`500 Internal Server Error`:
+ The Donau encountered an internal database error.
+ Returned with error code ``TALER_EC_GENERIC_DB_FETCH_FAILED``.
**Details:**
diff --git a/core/donau/post-charities.rst b/core/donau/post-charities.rst
@@ -13,18 +13,18 @@
:http:statuscode:`201 Created`:
The request was successful, and the response is a `CharityResponse`.
-
+ :http:statuscode:`400 Bad Request`:
+ The request body is malformed or required fields are missing.
+ Returned with error code ``TALER_EC_GENERIC_JSON_INVALID``.
:http:statuscode:`403 Forbidden`:
The request did not contain an accepted administrator bearer token in its header.
-
- :http:statuscode:`404 Not found`:
- The referenced resource needed to create the charity was not found. This response
- comes with a standard `ErrorDetail` response.
-
+ Returned with error code ``TALER_EC_GENERIC_TOKEN_PERMISSION_INSUFFICIENT``.
:http:statuscode:`409 Conflict`:
- A charity with the same public key exists in the backend, but it
- has different details. This response
- comes with a standard `ErrorDetail` response.
+ A charity with the same public key already exists.
+ Returned with error code ``TALER_EC_DONAU_CHARITY_PUB_EXISTS``.
+ :http:statuscode:`500 Internal Server Error`:
+ The Donau encountered a database error while storing the charity.
+ Returned with error code ``TALER_EC_GENERIC_DB_STORE_FAILED``.
.. ts:def:: CharityRequest
diff --git a/core/donau/post-csr-issue.rst b/core/donau/post-csr-issue.rst
@@ -9,15 +9,27 @@
**Response:**
- :http:statuscode:`200 OK`:
+ :http:statuscode:`201 Created`:
The request was successful, and the response is a `IssuePrepareResponse`. Note that repeating exactly the same request
will again yield the same response (assuming none of the donation unit is expired).
- :http:statuscode:`404 Not found`:
- The donation unit key is not known to the donau.
- :http:statuscode:`410 Gone`:
- The requested donation unit key is not yet or no longer valid. It either before the validity year, past the
- year or was revoked. The response is a `DonationUnitExpiredMessage`. Clients must evaluate the error code provided to
- understand which of the cases this is and handle it accordingly.
+ :http:statuscode:`400 Bad Request`:
+ The request body is malformed or required fields are missing,
+ or the specified denomination key does not support this operation.
+ Returned with error codes ``TALER_EC_GENERIC_JSON_INVALID`` or
+ ``TALER_EC_DONAU_GENERIC_INVALID_DENOMINATION_CIPHER_FOR_OPERATION``.
+ :http:statuscode:`404 Not Found`:
+ One of the referenced donation unit keys could not be found.
+ Returned with error code
+ ``TALER_EC_DONAU_GENERIC_DONATION_UNIT_UNKNOWN``.
+ :http:statuscode:`500 Internal Server Error`:
+ The donation unit key is not known to the Donau, has the wrong cipher type,
+ or the signing helper encountered an error.
+ Returned with error code ``TALER_EC_DONAU_GENERIC_KEYS_MISSING`` or
+ ``TALER_EC_DONAU_SIGNKEY_HELPER_BUG``.
+ :http:statuscode:`503 Service unavailable`:
+ The donau is lacking the keys to create the response.
+ Returned with error code
+ ``TALER_EC_DONAU_GENERIC_KEYS_MISSING``.
**Details:**
