clarify GET /kyc return values, add missing 503 case; fixes #7613

1 files changed, 12 insertions, 2 deletions

diff --git a/core/api-merchant.rst b/core/api-merchant.rst
index 1352b4e6..93e414e7 100644
--- a/core/api-merchant.rst
+++ b/core/api-merchant.rst
@@ -1276,15 +1276,25 @@ KYC status checks
     request should be repeated.
     The response will be an `AccountKycRedirects` object.
   :http:statuscode:`204 No content`:
-    All KYC operations queried have succeeded.
+    All KYC operations queried have succeeded.  This may change in the
+    future, but there is no need to check again soon. It is suggested
+    to check again at a frequency of hours or days.
   :http:statuscode:`502 Bad gateway`:
     We failed to obtain a response from an exchange (about the KYC status).
     The response will be an `AccountKycRedirects` object.
+  :http:statuscode:`503 Service unavailable`:
+    We do not know our KYC status as the exchange has not yet
+    returned the necessary details. This is not an actual failure:
+    this is expected to happen if for example a deposit was not yet aggregated
+    by the exchange and thus the exchange has not yet initiated
+    the KYC process. The client should simply try again later. It is
+    suggested to check again at a frequency of minutes to hours.
   :http:statuscode:`504 Gateway Timeout`:
     The merchant did not receive a confirmation from an exchange
     within the specified time period. Used when long-polling for the
     result.
-    The response will be an `AccountKycRedirects` object.
+
+  **Details:**
 
   .. ts:def:: AccountKycRedirects