summaryrefslogtreecommitdiff
path: root/core
diff options
context:
space:
mode:
Diffstat (limited to 'core')
-rw-r--r--core/api-auditor.rst9
-rw-r--r--core/api-bank-access.rst10
-rw-r--r--core/api-bank-integration.rst8
-rw-r--r--core/api-common.rst15
-rw-r--r--core/api-exchange.rst77
-rw-r--r--core/api-merchant.rst226
-rw-r--r--core/api-sync.rst32
-rw-r--r--core/api-wire.rst40
8 files changed, 214 insertions, 203 deletions
diff --git a/core/api-auditor.rst b/core/api-auditor.rst
index e76a72e2..74216bf7 100644
--- a/core/api-auditor.rst
+++ b/core/api-auditor.rst
@@ -40,7 +40,7 @@ know-your-customer (KYC) registration before issuing contracts.
**Response:**
- :status 200 OK:
+ :http:statuscode:`200 OK`:
The auditor responds with a `AuditorVersion`_ object. This request should
virtually always be successful.
@@ -85,7 +85,7 @@ know-your-customer (KYC) registration before issuing contracts.
**Response:**
- :status 200 OK:
+ :http:statuscode:`200 OK`:
The auditor responds with a :ts:type:`ExchangeList` object. This request should
virtually always be successful.
@@ -138,8 +138,9 @@ paid out first.
**Response:**
- :status 200: The auditor responds with a `DepositAudited` object.
- This request should virtually always be successful.
+ :http:statuscode:`200 Ok`:
+ The auditor responds with a `DepositAudited` object.
+ This request should virtually always be successful.
**Details:**
diff --git a/core/api-bank-access.rst b/core/api-bank-access.rst
index abd7d5c1..456211b7 100644
--- a/core/api-bank-access.rst
+++ b/core/api-bank-access.rst
@@ -118,8 +118,8 @@ name and account password, at least in the GNU Taler demo bank implementation.
Abort a withdrawal operation. Has no effect on an already aborted withdrawal operation.
- :status 200 OK: The withdrawal operation has been aborted. The response is an empty JSON object.
- :status 409 Conflict: The reserve operation has been confirmed previously and can't be aborted.
+ :http:statuscode:`200 OK`: The withdrawal operation has been aborted. The response is an empty JSON object.
+ :http:statuscode:`409 Conflict`: The reserve operation has been confirmed previously and can't be aborted.
.. http:POST:: ${BANK_API_BASE_URL}/accounts/${account_name}/withdrawals/${withdrawal_id}/confirm
@@ -128,8 +128,8 @@ name and account password, at least in the GNU Taler demo bank implementation.
**Response**
- :status 200 OK: The withdrawal operation has been confirmed. The response is an empty JSON object.
- :status 409 Conflict: The reserve operation has been aborted previously and can't be confirmed.
+ :http:statuscode:`200 OK`: The withdrawal operation has been confirmed. The response is an empty JSON object.
+ :http:statuscode:`409 Conflict`: The reserve operation has been aborted previously and can't be confirmed.
@@ -157,4 +157,4 @@ Registration (Testing)
**Response**
- :status 200 OK: Registration was successful
+ :http:statuscode:`200 OK`: Registration was successful
diff --git a/core/api-bank-integration.rst b/core/api-bank-integration.rst
index 09e674f2..07299d6a 100644
--- a/core/api-bank-integration.rst
+++ b/core/api-bank-integration.rst
@@ -34,7 +34,7 @@ to tightly integrate with GNU Taler.
**Response:**
- :status 200 OK:
+ :http:statuscode:`200 OK`:
The exchange responds with a `BankVersion` object. This request should
virtually always be successful.
@@ -79,7 +79,7 @@ for the withdrawal operation (the ``wopid``) to interact with the withdrawal ope
**Response**
- :status 200 OK:
+ :http:statuscode:`200 OK`:
The withdrawal operation is known to the bank, and details are given
in the `BankWithdrawalOperationStatus` response body.
@@ -121,10 +121,10 @@ for the withdrawal operation (the ``wopid``) to interact with the withdrawal ope
**Response**
- :status 200 OK:
+ :http:statuscode:`200 OK`:
The bank has accepted the withdrawal operation parameters chosen by the wallet.
The response is a `BankWithdrawalOperationPostResponse`.
- :status 404 Not Found:
+ :http:statuscode:`404 Not found`:
The bank does not know about a withdrawal operation with the specified ``wopid``.
**Details**
diff --git a/core/api-common.rst b/core/api-common.rst
index 12f4a360..5171a2c6 100644
--- a/core/api-common.rst
+++ b/core/api-common.rst
@@ -43,27 +43,28 @@ handle the error as if an internal error (500) had been returned.
**Response:**
:resheader Content-Type: application/json
- :status 200:
+
+ :http:statuscode:`200 Ok`:
The request was successful.
- :status 301 Moved Permanently:
+ :http:statuscode:`301 Moved permanently`:
The server responsible for the reserve
changed, the client MUST follow the link to the new location. If possible,
the client SHOULD remember the new URL for the reserve for future
requests. Only applicable if the request method is GET.
- :status 302 Found:
+ :http:statuscode:`302 Found`:
The server responsible for the reserve changed, the
client MUST follow the link to the new location, but MUST NOT retain the
new URL for future requests. Only applicable if the request method is GET.
- :status 307 Temporary Redirect:
+ :http:statuscode:`307 Temporary redirect`:
The server responsible for the reserve changed, the
client MUST follow the link to the new location, but MUST NOT retain the
new URL for future requests.
- :status 308 Permanent Redirect:
+ :http:statuscode:`308 Permanent redirect`:
The server responsible for the reserve
changed, the client MUST follow the link to the new location. If possible,
the client SHOULD remember the new URL for the reserve for future
requests.
- :status 500 Internal server error:
+ :http:statuscode:`500 Internal server error`:
This always indicates some serious internal operational error of the exchange,
such as a program bug, database problems, etc., and must not be used for
client-side problems. When facing an internal server error, clients should
@@ -76,7 +77,7 @@ handle the error as if an internal error (500) had been returned.
should naturally be able to address them in a timely fashion, especially
within 24h. When generating an internal server error, the exchange responds with
a JSON object containing the following fields:
- :status 400 Bad Request:
+ :http:statuscode:`400 Bad request`:
One of the arguments to the request is missing or malformed.
Unless specified otherwise, all error status codes (4xx and 5xx) have a message
diff --git a/core/api-exchange.rst b/core/api-exchange.rst
index 8b5c43cc..2b4f3b2d 100644
--- a/core/api-exchange.rst
+++ b/core/api-exchange.rst
@@ -97,10 +97,10 @@ possibly by using HTTPS.
**Response:**
- :status 200 OK:
+ :http:statuscode:`200 OK`:
The exchange responds with a `ExchangeKeysResponse` object. This request should
virtually always be successful.
- :status 403 Forbidden:
+ :http:statuscode:`403 Forbidden`:
The client specified the "now" argument, but the exchange does not allow this option as per its configuration.
**Details:**
@@ -288,7 +288,8 @@ Obtaining wire-transfer information
**Response:**
- :status 200: The exchange responds with a `WireResponse` object. This request should virtually always be successful.
+ :http:statuscode:`200 Ok`:
+ The exchange responds with a `WireResponse` object. This request should virtually always be successful.
**Details:**
@@ -390,9 +391,9 @@ exchange.
**Response:**
- :status 200 OK:
+ :http:statuscode:`200 OK`:
The exchange responds with a `ReserveStatus` object; the reserve was known to the exchange,
- :status 404 Not Found:
+ :http:statuscode:`404 Not found`:
The reserve key does not belong to a reserve known to the exchange.
**Details:**
@@ -526,14 +527,14 @@ exchange.
**Response:**
- :status 200 OK:
+ :http:statuscode:`200 OK`:
The request was successful, and the response is a `WithdrawResponse`. 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 coin signature to disk, the
coin is not lost.
- :status 403 Forbidden:
+ :http:statuscode:`403 Forbidden`:
The signature is invalid.
- :status 404 Not Found:
+ :http:statuscode:`404 Not found`:
The denomination key or the reserve are not known to the exchange. If the
denomination key is unknown, this suggests a bug in the wallet as the
wallet should have used current denomination keys from ``/keys``. If the
@@ -542,7 +543,7 @@ exchange.
not yet have completed and might be known to the exchange in the near future.
In this case, the wallet should repeat the exact same request later again
using exactly the same blinded coin.
- :status 403 Forbidden:
+ :http:statuscode:`403 Forbidden`:
The balance of the reserve is not sufficient to withdraw a coin of the indicated denomination.
The response is `WithdrawError` object.
@@ -624,15 +625,15 @@ denomination.
**Response:**
- :status 200 Ok:
+ :http:statuscode:`200 OK`:
The operation succeeded, the exchange confirms that no double-spending took
place. The response will include a `DepositSuccess` object.
- :status 401 Unauthorized:
+ :http:statuscode:`401 Unauthorized`:
One of the signatures is invalid.
- :status 404 Not Found:
+ :http:statuscode:`404 Not found`:
Either the denomination key is not recognized (expired or invalid) or
the wire type is not recognized.
- :status 409 Conflict:
+ :http:statuscode:`409 Conflict`:
The deposit operation has either failed because the coin has insufficient
residual value, or because the same public key of the coin has been
previously used with a different denomination. Which case it is
@@ -861,14 +862,14 @@ the API during normal operation.
exchange. The exchange MUST return a 307 or 308 redirection to the correct
base URL if this is the case.
- :status 200 OK:
+ :http:statuscode:`200 OK`:
The request was successful. The response body is `MeltResponse` in this case.
- :status 403 Forbidden:
+ :http:statuscode:`403 Forbidden`:
One of the signatures is invalid.
- :status 404 Not found:
+ :http:statuscode:`404 Not found`:
the exchange does not recognize the denomination key as belonging to the exchange,
or it has expired
- :status 409 Conflict:
+ :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
previously used with a different denomination. Which case it is
@@ -992,10 +993,10 @@ the API during normal operation.
not larger than the total remaining value of the coin before the melting
operations. Nevertheless, this is not really useful.
- :status 200 OK:
+ :http:statuscode:`200 OK`:
The transfer private keys matched the commitment and the original request was well-formed.
The response body is a `RevealResponse`
- :status 409 Conflict:
+ :http:statuscode:`409 Conflict`:
There is a problem between the original commitment and the revealed private
keys. The returned information is proof of the mismatch, and therefore
rather verbose, as it includes most of the original /refresh/melt request,
@@ -1062,11 +1063,11 @@ the API during normal operation.
**Response:**
- :status 200 OK:
+ :http:statuscode:`200 OK`:
All commitments were revealed successfully. The exchange returns an array,
typically consisting of only one element, in which each each element contains
information about a melting session that the coin was used in.
- :status 404 Not Found:
+ :http:statuscode:`404 Not found`:
The exchange has no linkage data for the given public key, as the coin has not
yet been involved in a refresh operation.
@@ -1135,19 +1136,19 @@ in using this API.
**Response:**
- :status 200 OK:
+ :http:statuscode:`200 OK`:
The request was successful, and the response is a `RecoupConfirmation`.
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 coin signature to disk, the
coin is not lost.
- :status 401 Unauthorized:
+ :http:statuscode:`401 Unauthorized`:
The coin's signature is invalid.
- :status 404 Not Found:
+ :http:statuscode:`404 Not found`:
The denomination key is not in the set of denomination
keys where emergency pay back is enabled, or the blinded
coin is not known to have been withdrawn.
- :status 409 Conflict:
+ :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
previously used with a different denomination. Which case it is
@@ -1246,10 +1247,10 @@ typically also view the balance.)
**Response:**
- :status 200 OK:
+ :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`.
- :status 404 Not Found:
+ :http:statuscode:`404 Not found`:
The wire transfer identifier is unknown to the exchange.
.. ts:def:: TrackTransferResponse
@@ -1314,16 +1315,18 @@ typically also view the balance.)
**Response:**
- :status 200 OK:
+ :http:statuscode:`200 OK`:
The deposit has been executed by the exchange and we have a wire transfer identifier.
The response body is a `TrackTransactionResponse` object.
- :status 202 Accepted:
+ :http:statuscode:`202 Accepted`:
The deposit request has been accepted for processing, but was not yet
executed. Hence the exchange does not yet have a wire transfer identifier. The
merchant should come back later and ask again.
The response body is a `TrackTransactionAcceptedResponse`.
- :status 401 Unauthorized: The signature is invalid.
- :status 404 Not Found: The deposit operation is unknown to the exchange
+ :http:statuscode:`401 Unauthorized`:
+ The signature is invalid.
+ :http:statuscode:`404 Not found`:
+ The deposit operation is unknown to the exchange
**Details:**
@@ -1375,20 +1378,20 @@ Refunds
**Response:**
- :status 200 Ok:
+ :http:statuscode:`200 OK`:
The operation succeeded, the exchange confirms that the coin can now be refreshed. The response will include a `RefundSuccess` object.
- :status 401 Unauthorized:
+ :http:statuscode:`401 Unauthorized`:
Merchant signature is invalid.
This response comes with a standard `ErrorDetail` response.
- :status 404 Not found:
+ :http:statuscode:`404 Not found`:
The refund operation failed as we could not find a matching deposit operation (coin, contract, transaction ID and merchant public key must all match).
This response comes with a standard `ErrorDetail` response.
- :status 409 Conflict:
+ :http:statuscode:`409 Conflict`:
The exchange has previously received a refund request for the same coin, merchant and contract, but specifying a different amount for the same refund transaction ID. The response will be a `RefundFailure` object.
- :status 410 Gone:
+ :http:statuscode:`410 Gone`:
It is too late for a refund by the exchange, the money was already sent to the merchant.
This response comes with a standard `ErrorDetail` response.
- :status 412 Precondition Failed:
+ :http:statuscode:`412 Precondition failed`:
The request transaction ID is identical to a previous refund request by the same
merchant for the same coin and contract, but the refund amount differs. (The
failed precondition is that the ``rtransaction_id`` is not unique.)
diff --git a/core/api-merchant.rst b/core/api-merchant.rst
index 53b64243..8def6721 100644
--- a/core/api-merchant.rst
+++ b/core/api-merchant.rst
@@ -48,7 +48,7 @@ such as the implemented version of the protocol and the currency used.
**Response:**
- :status 200 OK:
+ :http:statuscode:`200 OK`:
The exchange accepted all of the coins. The body is a `VersionResponse`.
.. ts:def:: VersionResponse
@@ -122,12 +122,12 @@ claim orders (say in a case where stocks are limited).
**Response:**
- :status 200 OK:
+ :http:statuscode:`200 OK`:
The client has successfully claimed the order.
The response contains the :ref:`contract terms <contract-terms>`.
- :status 404 Not found:
+ :http:statuscode:`404 Not found`:
The backend is unaware of the instance or order.
- :status 409 Conflict:
+ :http:statuscode:`409 Conflict`:
The someone else claimed the same order ID with different nonce before.
.. ts:def:: ClaimResponse
@@ -157,12 +157,12 @@ Making the payment
**Response:**
- :status 200 OK:
+ :http:statuscode:`200 OK`:
The exchange accepted all of the coins.
The body is a `payment response <PaymentResponse>`.
The ``frontend`` should now fulfill the contract.
Note that it is possible that refunds have been granted.
- :status 400 Bad request:
+ :http:statuscode:`400 Bad request`:
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.
@@ -170,25 +170,25 @@ Making the payment
There used to be a sufficient payment, but due to refunds the amount effectively
paid is no longer sufficient. (If the amount is generally insufficient, we
return "406 Not Acceptable", only if this is because of refunds we return 402.)
- :status 403 Forbidden:
+ :http:statuscode:`403 Forbidden`:
One of the coin signatures was not valid.
- :status 404 Not found:
+ :http:statuscode:`404 Not found`:
The merchant backend could not find the order or the instance and thus cannot process the payment.
- :status 406 Not Acceptable:
+ :http:statuscode:`406 Not acceptable`:
The payment is insufficient (sum is below the required total amount).
- :status 408 Request Timeout:
+ :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.
- :status 409 Conflict:
+ :http:statuscode:`409 Conflict`:
The exchange rejected the payment because a coin was already spent before.
The response will include the ``coin_pub`` for which the payment failed,
in addition to the response from the exchange to the ``/deposit`` request.
- :status 410 Gone:
+ :http:statuscode:`410 Gone`:
The offer has expired and is no longer available.
- :status 412 Precondition Failed:
+ :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.
- :status 424 Failed Dependency:
+ :http:statuscode:`424 Failed dependency`:
The merchant's interaction with the exchange failed in some way.
The client might want to try later again.
This includes failures like the denomination key of a coin not being
@@ -277,22 +277,22 @@ Querying payment status
**Response:**
- :status 200 OK:
+ :http:statuscode:`200 OK`:
The response is a `StatusPaidResponse`.
- :status 202 Accepted:
+ :http:statuscode:`202 Accepted`:
The response is a `StatusGotoResponse`. Only returned if the content type requested was not HTML.
- :status 302 Found:
+ :http:statuscode:`302 Found`:
The client should go to the indicated location. Only returned if the content type requested was HTML.
- :status 402 PaymentRequired:
+ :http:statuscode:`402 Payment required`:
The response is a `StatusUnpaidResponse`.
- :status 403 Forbidden:
+ :http:statuscode:`403 Forbidden`:
The ``h_contract`` (or the ``token`` for unclaimed orders) does not match the order
and we have no fulfillment URL in the contract.
- :status 410 Gone:
+ :http:statuscode:`410 Gone`:
The response is a `StatusGoneResponse`.
- :status 404 Not found:
+ :http:statuscode:`404 Not found`:
The merchant backend is unaware of the order.
- :status 406 Not Acceptable:
+ :http:statuscode:`406 Not acceptable`:
The merchant backend could not load the template required to generate a reply in the desired format. (Likely HTML templates were not properly installed.)
.. ts:def:: StatusPaidResponse
@@ -374,20 +374,20 @@ again.
**Response:**
- :status 204 No content:
+ :http:statuscode:`204 No content`:
The merchant accepted the signature.
The ``frontend`` should now fulfill the contract.
Note that it is possible that refunds have been granted.
- :status 400 Bad request:
+ :http:statuscode:`400 Bad request`:
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.
- :status 403 Forbidden:
+ :http:statuscode:`403 Forbidden`:
The signature was not valid.
- :status 404 Not found:
+ :http:statuscode:`404 Not found`:
The merchant backend could not find the order or the instance
and thus cannot process the request.
- :status 409 Conflict:
+ :http:statuscode:`409 Conflict`:
The provided contract hash does not match this order.
.. ts:def:: PaidRequest
@@ -436,29 +436,29 @@ are for incomplete payments for an order and never for established contracts.
**Response:**
- :status 200 OK:
+ :http:statuscode:`200 OK`:
The merchant accepted the request, and passed it on to the exchange. The body is a
a `merchant refund response <MerchantRefundResponse>`. Note that the exchange
MAY still have encountered errors in processing. Those will then be part of
the body. Wallets MUST carefully consider errors for each of the coins as
returned by the exchange.
- :status 400 Bad request:
+ :http:statuscode:`400 Bad request`:
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.
- :status 403 Forbidden:
+ :http:statuscode:`403 Forbidden`:
The ``h_contract`` does not match the $ORDER_ID.
- :status 404 Not found:
+ :http:statuscode:`404 Not found`:
The merchant backend could not find the order or the instance
and thus cannot process the abort request.
- :status 408 Request Timeout:
+ :http:statuscode:`408 Request timeout`:
The merchant backend took too long getting a response from the exchange.
The wallet SHOULD retry soon.
- :status 412 Precondition Failed:
+ :http:statuscode:`412 Precondition failed`:
Aborting the payment is not allowed, as the original payment did succeed.
It is possible that a different wallet succeeded with the payment. This
wallet should thus try to refresh all of the coins involved in the payment.
- :status 424 Failed Dependency:
+ :http:statuscode:`424 Failed dependency`:
The merchant's interaction with the exchange failed in some way.
The error from the exchange is included.
@@ -573,13 +573,13 @@ the contract. Refunds must be approved by the merchant's business logic.
**Response:**
- :status 200 OK:
+ :http:statuscode:`200 OK`:
The response is a `WalletRefundResponse`.
- :status 204 No content:
+ :http:statuscode:`204 No content`:
There are no refunds for the order.
- :status 403 Forbidden:
+ :http:statuscode:`403 Forbidden`:
The ``h_contract`` does not match the order.
- :status 404 Not found:
+ :http:statuscode:`404 Not found`:
The merchant backend is unaware of the order.
.. ts:def:: WalletRefundRequest
@@ -690,13 +690,13 @@ a website.
**Response:**
- :status 200 OK:
+ :http:statuscode:`200 OK`:
A tip is being returned. The backend responds with a `TipInformation`.
- :status 404 Not Found:
+ :http:statuscode:`404 Not found`:
The tip identifier is unknown.
- :status 406 Not Acceptable:
+ :http:statuscode:`406 Not acceptable`:
The merchant backend could not load the template required to generate a reply in the desired format. (Likely HTML templates were not properly installed.)
- :status 410 Gone:
+ :http:statuscode:`410 Gone`:
A tip has been fully claimed. The JSON reply still contains the `TipInformation`.
.. ts:def:: TipInformation
@@ -726,15 +726,15 @@ a website.
**Response:**
- :status 200 OK:
+ :http:statuscode:`200 OK`:
A tip is being returned. The backend responds with a `TipResponse`
- :status 401 Unauthorized:
+ :http:statuscode:`401 Unauthorized`:
The tip amount requested exceeds the tip.
- :status 404 Not Found:
+ :http:statuscode:`404 Not found`:
The tip identifier is unknown.
- :status 409 Conflict:
+ :http:statuscode:`409 Conflict`:
Some of the denomination key hashes of the request do not match those currently available from the exchange (hence there is a conflict between what the wallet requests and what the merchant believes the exchange can provide).
- :status 410 Gone:
+ :http:statuscode:`410 Gone`:
The tip has expired.
.. ts:def:: TipPickupRequest
@@ -796,9 +796,9 @@ Setting up instances
**Response:**
- :status 204 No content:
+ :http:statuscode:`204 No content`:
The backend has successfully created the instance.
- :status 409 Conflict:
+ :http:statuscode:`409 Conflict`:
This instance already exists, but with other configuration options.
Use "PATCH" to update an instance configuration.
@@ -863,9 +863,9 @@ Setting up instances
**Response:**
- :status 204 No content:
+ :http:statuscode:`204 No content`:
The backend has successfully created the instance.
- :status 404 Not found:
+ :http:statuscode:`404 Not found`:
This instance is unknown and thus cannot be reconfigured.
.. ts:def:: InstanceReconfigurationMessage
@@ -921,7 +921,7 @@ Inspecting instances
**Response:**
- :status 200 OK:
+ :http:statuscode:`200 OK`:
The backend has successfully returned the list of instances stored. Returns
a `InstancesResponse`.
@@ -962,7 +962,7 @@ Inspecting instances
**Response:**
- :status 200 OK:
+ :http:statuscode:`200 OK`:
The backend has successfully returned the list of instances stored. Returns
a `QueryInstancesResponse`.
@@ -1047,11 +1047,11 @@ Deleting instances
**Response**
- :status 204 No content:
+ :http:statuscode:`204 No content`:
The backend has successfully removed the instance. The body is empty.
- :status 404 Not found:
+ :http:statuscode:`404 Not found`:
The instance is unknown to the backend.
- :status 409 Conflict:
+ :http:statuscode:`409 Conflict`:
The instance cannot be deleted because it has pending offers, or
the instance cannot be purged because it has successfully processed
payments that have not passed the TAX_RECORD_EXPIRATION time.
@@ -1084,9 +1084,9 @@ Adding products to the inventory
**Response:**
- :status 204 No content:
+ :http:statuscode:`204 No content`:
The backend has successfully expanded the inventory.
- :status 409 Conflict:
+ :http:statuscode:`409 Conflict`:
The backend already knows a product with this product ID, but with different details.
@@ -1154,7 +1154,7 @@ Adding products to the inventory
**Response:**
- :status 204 No content:
+ :http:statuscode:`204 No content`:
The backend has successfully expanded the inventory.
@@ -1210,7 +1210,7 @@ Inspecting inventory
**Response:**
- :status 200 OK:
+ :http:statuscode:`200 OK`:
The backend has successfully returned the inventory. Returns
a `InventorySummaryResponse`.
@@ -1238,7 +1238,7 @@ Inspecting inventory
**Response:**
- :status 200 OK:
+ :http:statuscode:`200 OK`:
The backend has successfully returned the inventory. Returns
a `ProductDetail`.
@@ -1316,11 +1316,11 @@ Reserving inventory
**Response:**
- :status 204 No content:
+ :http:statuscode:`204 No content`:
The backend has successfully locked (or unlocked) the requested ``quantity``.
- :status 404 Not found:
+ :http:statuscode:`404 Not found`:
The backend has does not know this product.
- :status 410 Gone:
+ :http:statuscode:`410 Gone`:
The backend does not have enough of product in stock.
.. ts:def:: LockRequest
@@ -1348,11 +1348,11 @@ Removing products from inventory
**Response:**
- :status 204 No content:
+ :http:statuscode:`204 No content`:
The backend has successfully deleted the product.
- :status 404 Not found:
+ :http:statuscode:`404 Not found`:
The backend does not know the instance or the product.
- :status 409 Conflict:
+ :http:statuscode:`409 Conflict`:
The backend refuses to delete the product because it is locked.
@@ -1392,17 +1392,17 @@ Creating orders
**Response:**
- :status 200 OK:
+ :http:statuscode:`200 OK`:
The backend has successfully created the proposal. The response is a
:ts:type:`PostOrderResponse`.
- :status 404 Not found:
+ :http:statuscode:`404 Not found`:
The order given used products from the inventory, but those were not found
in the inventory. Or the merchant instance is unknown (including possibly the instance being not configured for new orders). Details in the
error code. NOTE: no good way to find out which product is not in the
inventory, we MAY want to specify that in the reply.
- :status 409 Conflict:
+ :http:statuscode:`409 Conflict`:
A different proposal already exists under the specified order ID.
- :status 410 Gone:
+ :http:statuscode:`410 Gone`:
The order given used products from the inventory that are out of stock.
The response is a :ts:type:`OutOfStockResponse`.
@@ -1550,7 +1550,7 @@ Inspecting orders
**Response:**
- :status 200 OK:
+ :http:statuscode:`200 OK`:
The response is an `OrderHistory`.
.. ts:def:: OrderHistory
@@ -1608,11 +1608,11 @@ Inspecting orders
**Response:**
- :status 200 OK:
+ :http:statuscode:`200 OK`:
Returns a `MerchantOrderStatusResponse`, whose format can differ based on the status of the payment.
- :status 404 Not Found:
+ :http:statuscode:`404 Not found`:
The order or instance is unknown to the backend.
- :status 424 Failed dependency:
+ :http:statuscode:`424 Failed dependency`:
We failed to obtain a response from the exchange (about the wire transfer status).
.. ts:def:: MerchantOrderStatusResponse
@@ -1797,15 +1797,15 @@ the contract!) to minimize risks from information leakage.
**Response:**
- :status 200 OK:
+ :http:statuscode:`200 OK`:
The merchant deleted the specified fields from the contract of
order $ORDER_ID.
- :status 400 Bad request:
+ :http:statuscode:`400 Bad request`:
The request is malformed or one of the paths is invalid.
- :status 404 Not found:
+ :http:statuscode:`404 Not found`:
The merchant backend could not find the order or the instance
and thus cannot process the abort request.
- :status 409 Conflict:
+ :http:statuscode:`409 Conflict`:
The request includes a field that was not marked as forgettable, so
the merchant cannot delete that field.
@@ -1827,11 +1827,11 @@ the contract!) to minimize risks from information leakage.
**Response:**
- :status 204 No content:
+ :http:statuscode:`204 No content`:
The backend has successfully deleted the order.
- :status 404 Not found:
+ :http:statuscode:`404 Not found`:
The backend does not know the instance or the order.
- :status 409 Conflict:
+ :http:statuscode:`409 Conflict`:
The backend refuses to delete the order.
@@ -1852,16 +1852,16 @@ Giving Refunds
**Response:**
- :status 200 OK:
+ :http:statuscode:`200 OK`:
The refund amount has been increased, the backend responds with a `MerchantRefundResponse`
- :status 403 Forbidden:
+ :http:statuscode:`403 Forbidden`:
For the given order, the refund delay was zero and thus refunds are categorically not allowed.
- :status 404 Not found:
+ :http:statuscode:`404 Not found`:
The order is unknown to the merchant
- :status 410 Gone:
+ :http:statuscode:`410 Gone`:
It is too late for aborting, the exchange may have already wired the funds
to the merchant.
- :status 409 Conflict:
+ :http:statuscode:`409 Conflict`:
The refund amount exceeds the amount originally paid
.. ts:def:: RefundRequest
@@ -1915,10 +1915,10 @@ Informing the backend about incoming wire transfers
**Response:**
- :status 200 OK:
+ :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 `MerchantTrackTransferResponse`.
- :status 202 Accepted:
+ :http:statuscode:`202 Accepted`:
The exchange provided conflicting information about the transfer. Namely,
there is at least one deposit among the deposits aggregated by ``wtid``
that accounts for a coin whose
@@ -1932,12 +1932,12 @@ Informing the backend about incoming wire transfers
the bad behavior to the auditor -- and then hope for the auditor to
resolve it. So in that respect, 202 is the right status code as more
work remains to be done for a final resolution.)
- :status 404 Not Found:
+ :http:statuscode:`404 Not found`:
The instance is unknown to the exchange.
- :status 409 Conflict:
+ :http:statuscode:`409 Conflict`:
The wire transfer identifier is already known to us, but for a different amount,
wire method or exchange.
- :status 424 Failed Dependency:
+ :http:statuscode:`424 Failed dependency`:
The exchange returned an error when we asked it about the "GET /transfer" status
for this wire transfer. Details of the exchange error are returned.
@@ -2153,7 +2153,7 @@ Querying known wire transfers
**Response:**
- :status 200 OK:
+ :http:statuscode:`200 OK`:
The body of the response is a `TransferList`.
.. ts:def:: TransferList
@@ -2241,14 +2241,14 @@ funds to the exchange.
**Response:**
- :status 200 OK:
+ :http:statuscode:`200 OK`:
The backend is waiting for the reserve to be established. The merchant
must now perform the wire transfer indicated in the `ReserveCreateConfirmation`.
- :status 408 Request Timeout:
+ :http:statuscode:`408 Request timeout`:
The exchange did not respond on time.
- :status 409 Conflict:
+ :http:statuscode:`409 Conflict`:
The exchange does not support the requested wire method.
- :status 424 Failed Dependency:
+ :http:statuscode:`424 Failed dependency`:
We could not obtain /wire details from the specified exchange base URL.
.. ts:def:: ReserveCreateRequest
@@ -2286,7 +2286,7 @@ funds to the exchange.
**Response:**
- :status 200 OK:
+ :http:statuscode:`200 OK`:
Returns a list of known tipping reserves.
The body is a `TippingReserveStatus`.
@@ -2340,11 +2340,11 @@ Query funds remaining
**Response:**
- :status 200 OK:
+ :http:statuscode:`200 OK`:
Returns the `ReserveDetail`.
- :status 404 Not found:
+ :http:statuscode:`404 Not found`:
The tipping reserve is not known.
- :status 424 Failed Dependency:
+ :http:statuscode:`424 Failed dependency`:
We are having trouble with the request because of a problem with the exchange.
Likely returned with an "exchange_code" in addition to a "code" and
an "exchange_http_status" in addition to our own HTTP status. Also usually
@@ -2411,11 +2411,11 @@ Authorizing tips
**Response:**
- :status 200 OK:
+ :http:statuscode:`200 OK`:
A tip has been created. The backend responds with a `TipCreateConfirmation`
- :status 404 Not Found:
+ :http:statuscode:`404 Not found`:
The instance or the reserve is unknown to the backend.
- :status 412 Precondition Failed:
+ :http:statuscode:`412 Precondition failed`:
The tip amount requested exceeds the available reserve balance for tipping.
.. ts:def:: TipCreateRequest
@@ -2463,11 +2463,11 @@ Authorizing tips
**Response:**
- :status 200 OK:
+ :http:statuscode:`200 OK`:
A tip has been created. The backend responds with a `TipCreateConfirmation`
- :status 404 Not Found:
+ :http:statuscode:`404 Not found`:
The instance is unknown to the backend.
- :status 412 Precondition Failed:
+ :http:statuscode:`412 Precondition failed`:
The tip amount requested exceeds the available reserve balance for tipping
in all of the reserves of the instance.
@@ -2489,11 +2489,11 @@ Deleting reserves
**Response:**
- :status 204 No content:
+ :http:statuscode:`204 No content`:
The backend has successfully deleted the reserve.
- :status 404 Not found:
+ :http:statuscode:`404 Not found`:
The backend does not know the instance or the reserve.
- :status 409 Conflict:
+ :http:statuscode:`409 Conflict`:
The backend refuses to delete the reserve (committed tips awaiting pickup).
@@ -2510,9 +2510,9 @@ Checking tip status
**Response:**
- :status 200 OK:
+ :http:statuscode:`200 OK`:
The tip is known. The backend responds with a `TipDetails` message
- :status 404 Not Found:
+ :http:statuscode:`404 Not found`:
The tip is unknown to the backend.
.. ts:def:: TipDetails
@@ -2566,7 +2566,7 @@ Checking tip status
**Response:**
- :status 200 OK:
+ :http:statuscode:`200 OK`:
The backend has successfully found the list of tips. The backend responds
with a `TipsResponse`.
diff --git a/core/api-sync.rst b/core/api-sync.rst
index 650cd8a7..1e673ed6 100644
--- a/core/api-sync.rst
+++ b/core/api-sync.rst
@@ -156,28 +156,28 @@ Receiving Terms of Service
**Response**
- :status 200 OK:
+ :http:statuscode:`200 OK`:
The body contains the current version of the backup
as known to the server.
- :status 204 No content:
+ :http:statuscode:`204 No content`:
This is a fresh account, no previous backup data exists at
the server.
- :status 304 Not modified:
+ :http:statuscode:`304 Not modified`:
The version available at the server is identical to that
specified in the "If-None-Match" header.
- :status 404 Not found:
+ :http:statuscode:`404 Not found`:
The backup service is unaware of a matching account.
- :status 410 Gone:
+ :http:statuscode:`410 Gone`:
The backup service has closed operations. The body will
contain the latest version still available at the server.
The body may be empty if no version is available.
The user should be urged to find another provider.
- :status 429 Too many requests:
+ :http:statuscode:`429 Too many requests`:
This account has exceeded thresholds for the number of
requests. The client should try again later, and may want
to decrease its synchronization frequency.
@@ -249,52 +249,52 @@ Receiving Terms of Service
**Response**
- :status 204 No content:
+ :http:statuscode:`204 No content`:
The transfer was successful, and the server has registered
the new version.
- :status 304 Not modified:
+ :http:statuscode:`304 Not modified`:
The server is already aware of this version of the client.
Returned before 100 continue to avoid upload.
- :status 400 Bad request:
+ :http:statuscode:`400 Bad request`:
Most likely, the uploaded body is too short (less than 32 bytes).
- :status 402 Payment required:
+ :http:statuscode:`402 Payment required`:
The synchronization service requires payment before the
account can continue to be used. The fulfillment URL
should be the /$ACCOUNT-KEY URL, but can be safely ignored
by the client. The contract should be shown to the user
in the canonical dialog, possibly in a fresh tab.
- :status 403 Forbidden:
+ :http:statuscode:`403 Forbidden`:
The signature is invalid or missing (or body does not match).
- :status 409 Conflict:
+ :http:statuscode:`409 Conflict`:
The server has a more recent version than what is given
in "If-Match". The more recent version is returned. The
client should merge the two versions and retry using the
given response's "E-Tag" in the next attempt in "If-Match".
- :status 410 Gone:
+ :http:statuscode:`410 Gone`:
The backup service has closed operations. The body will
contain the latest version still available at the server.
The body may be empty if no version is available.
The user should be urged to find another provider.
- :status 411 Length required:
+ :http:statuscode:`411 Length required`:
The client must specify the "Content-length" header before
attempting upload. While technically optional by the
HTTP specification, the synchronization service may require
the client to provide the length upfront.
- :status 413 Request Entity Too Large:
+ :http:statuscode:`413 Request entity too large`:
The requested upload exceeds the quota for the type of
account. The client should suggest to the user to
migrate to another backup and synchronization service
(like with "410 Gone").
- :status 429 Too many requests:
+ :http:statuscode:`429 Too many requests`:
This account has exceeded daily thresholds for the number of
requests. The client should try again later, and may want
to decrease its synchronization frequency.
diff --git a/core/api-wire.rst b/core/api-wire.rst
index 676c8029..ce8c94e4 100644
--- a/core/api-wire.rst
+++ b/core/api-wire.rst
@@ -49,13 +49,16 @@ Making Transactions
**Response:**
- :status 200 OK:
+ :http:statuscode:`200 OK`:
The request has been correctly handled, so the funds have been transferred to
the recipient's account. The body is a `TransferResponse`
- :status 400 Bad Request: Request malformed. The bank replies with an `ErrorDetail` object.
- :status 401 Unauthorized: Authentication failed, likely the credentials are wrong.
- :status 404 Not found: The endpoint is wrong or the user name is unknown. The bank replies with an `ErrorDetail` object.
- :status 409 Conflict:
+ :http:statuscode:`400 Bad request`:
+ Request malformed. The bank replies with an `ErrorDetail` object.
+ :http:statuscode:`401 Unauthorized`:
+ Authentication failed, likely the credentials are wrong.
+ :http:statuscode:`404 Not found`:
+ The endpoint is wrong or the user name is unknown. The bank replies with an `ErrorDetail` object.
+ :http:statuscode:`409 Conflict`:
A transaction with the same ``transaction_uid`` but different transaction details
has been submitted before.
@@ -156,10 +159,10 @@ Querying the transaction history
**Response**
- :status 200 OK: JSON object of type `IncomingHistory`.
- :status 400 Bad Request: Request malformed. The bank replies with an `ErrorDetail` object.
- :status 401 Unauthorized: Authentication failed, likely the credentials are wrong.
- :status 404 Not found: The endpoint is wrong or the user name is unknown. The bank replies with an `ErrorDetail` object.
+ :http:statuscode:`200 OK`: JSON object of type `IncomingHistory`.
+ :http:statuscode:`400 Bad request`: Request malformed. The bank replies with an `ErrorDetail` object.
+ :http:statuscode:`401 Unauthorized`: Authentication failed, likely the credentials are wrong.
+ :http:statuscode:`404 Not found`: The endpoint is wrong or the user name is unknown. The bank replies with an `ErrorDetail` object.
.. ts:def:: IncomingHistory
@@ -238,10 +241,10 @@ Querying the transaction history
**Response**
- :status 200 OK: JSON object of type `OutgoingHistory`.
- :status 400 Bad Request: Request malformed. The bank replies with an `ErrorDetail` object.
- :status 401 Unauthorized: Authentication failed, likely the credentials are wrong.
- :status 404 Not found: The endpoint is wrong or the user name is unknown. The bank replies with an `ErrorDetail` object.
+ :http:statuscode:`200 OK`: JSON object of type `OutgoingHistory`.
+ :http:statuscode:`400 Bad request`: Request malformed. The bank replies with an `ErrorDetail` object.
+ :http:statuscode:`401 Unauthorized`: Authentication failed, likely the credentials are wrong.
+ :http:statuscode:`404 Not found`: The endpoint is wrong or the user name is unknown. The bank replies with an `ErrorDetail` object.
.. ts:def:: OutgoingHistory
@@ -296,12 +299,15 @@ exposed by bank gateways in production.
**Response:**
- :status 200 OK:
+ :http:statuscode:`200 OK`:
The request has been correctly handled, so the funds have been transferred to
the recipient's account. The body is a `AddIncomingResponse`
- :status 400 Bad Request: The request is malformed. The bank replies with an `ErrorDetail` object.
- :status 401 Unauthorized: Authentication failed, likely the credentials are wrong.
- :status 404 Not found: The endpoint is wrong or the user name is unknown. The bank replies with an `ErrorDetail` object.
+ :http:statuscode:`400 Bad request`:
+ The request is malformed. The bank replies with an `ErrorDetail` object.
+ :http:statuscode:`401 Unauthorized`:
+ Authentication failed, likely the credentials are wrong.
+ :http:statuscode:`404 Not found`:
+ The endpoint is wrong or the user name is unknown. The bank replies with an `ErrorDetail` object.
.. ts:def:: AddIncomingRequest