fix(docs): update validation error status code information, closes #210

docs/authentication.rst

@@ -260,21 +260,27 @@ old email address for informational purposes.
 Delete Account
 ``````````````
 
-To delete your account, send a ``POST`` request with your email address and
-password to the ``/auth/account/delete/`` endpoint::
+Before you can delete your account, it is required to first delete all your
+domains from deSEC (see `Deleting a Domain`_).
+
+To delete your (empty) account, send a ``POST`` request with your email
+address and password to the ``/auth/account/delete/`` endpoint::
 
     curl -X POST https://desec.io/api/v1/auth/account/delete/ \
         --header "Content-Type: application/json" --data @- <<< \
         '{"email": "youremailaddress@example.com", "password": "yourpassword"}'
 
-You will receive an email with a link of the form
-``https://desec.io/api/v1/v/delete-account/<code>/``. To actually delete your
-account, send a ``GET`` request using this link (i.e., you can simply click
-the link).
+If the correct password has been provided, the server will reply with ``202
+Accepted`` and send you an email with a link of the form
+``https://desec.io/api/v1/v/delete-account/<code>/``. To finish the deletion,
+send a ``GET`` request using this link (i.e., you can simply click the link).
 
 The link expires after 12 hours. It is also invalidated by certain other
 account-related activities, such as changing your email address or password.
 
+If your account still contains domains, the server will respond with ``409
+Conflict`` and not delete your account.
+
 
 Log Out
 ```````

docs/domains.rst

@@ -108,16 +108,13 @@ endpoint, like this::
 Only the ``name`` field is mandatory.
 
 Upon success, the response status code will be ``201 Created``, with the
-domain object contained in the response body.  ``400 Bad Request`` is returned
-if the request contained malformed data.  If the object could not be
-created although the request was wellformed, the API responds with ``403
-Forbidden`` if the maximum number of domains for this user has been reached,
-and with ``409 Conflict`` otherwise.  This can happen, for example, if there
-already is a domain with the same name or if the domain name is considered
-invalid for policy reasons.
-
-The response body *may* provide further, human-readable information on the
-policy violation that occurred.
+domain object contained in the response body.  If an improper request was
+sent, ``400 Bad Request`` is returned.  This can happen when the request
+payload was malformed, or when the requested domain name is unavailable or
+invalid (e.g. because another user owns it, or due to policy reasons).
+
+If you have reached the maximum number of domains for your account, the API
+responds with ``403 Forbidden``.
 
 Restrictions on what is a valid domain name apply.  In particular, domains
 listed on the `Public Suffix List`_ cannot be registered.  (If you operate a

docs/rrsets.rst

@@ -129,9 +129,9 @@ field is optional.
 
 Upon success, the response status code will be ``201 Created``, with the RRset
 contained in the response body.  If another RRset with the same name and type
-exists already, the API responds with ``409 Conflict``.  If there is a
-syntactical error (e.g. not all required fields were provided or the type was
-not specified in uppercase), the API responds with ``400 Bad Request``.  If
+exists already, the API responds with ``400 Bad Request``.  The same status
+code is returned If there is a syntactical error (e.g. not all required fields
+were provided or the type was not specified in uppercase).  If
 field values were semantically invalid (e.g. when you provide an unknown record
 type, or an `A` value that is not an IPv4 address), ``422 Unprocessable
 Entity`` is returned.
@@ -448,37 +448,35 @@ records to ``[]``.
 
 Input validation
 ````````````````
-For efficiency and other reasons, there are three stages of input validation:
+There are two stages of input validation:
 
-1. Basic syntactical and semantical checks for missing JSON fields, negative
-   TTL and such.
+1. Sanity checks, such as syntax, basic semantics (e.g. negative TTL), and
+   uniqueness checks. (We both check for uniqueness with respect to
+   pre-existing RRsets as well as with respect to other RRsets sent in the
+   same bulk request.)
 
-2. Uniqueness validation.  This is both to avoid the creation of multiple
-   RRsets with the same subname and type, and to uncover bulk requests
-   containing multiple parts that refer to the same subname and type.
+2. DNS conformity checks, such as whether the given type is a supported record
+   type, and whether the given record contents are consistent with the type.
 
-3. Lastly, we check whether the given type is a supported DNS record type, and
-   whether the given record contents are consistent with the type.
+If an error occurs in the first validation stage, the request is aborted, and
+the error(s) are returned.  Only if no error occurred, will the request be
+allowed to proceed to the second stage.
 
-Errors are collected at each stage; if at least one error occured, the request
-is aborted at the end of the stage, and the error(s) are returned.  Only if no
-error occurred, will the request be allowed to proceed to the next stage.
-
-In stages 1 and 2, errors are presented as a list of errors, with each list
+In the first stage, errors are presented as a list of errors, with each list
 item referring to one part of the bulk request, in the same order.  Parts that
 did not cause errors have an empty error object ``{}``, and parts with errors
-contain more details describing the error.  Unfortunately, in step 3, the API
+contain more details describing the error.  Unfortunately, in step 2, the API
 currently does not associate the error message with the RRset that caused it.
 
-The successive treatment of stages 1 and 2 means that one bulk part with a
-stage-2 error may appear valid (``{}``) as long as another RRset has a stage-1
-error.  Only after the stage-1 error is resolved, the request will reach stage
-2, at which point an error may occur for the bulk part that previously seemed
+The successive treatment of stages means that one bulk part with a stage-2
+error may appear valid (``{}``) as long as another RRset has a stage-1 error.
+Only after the stage-1 error is resolved, the request will reach stage 2, at
+which point an error may appear due to a bulk part that previously seemed
 valid.
 
-Errors in stages 1 and 2 cause status code ``400`` (regardless of the exact
-reason(s) which may vary across bulk parts), and errors from stage 3 cause
-status code ``422``.
+Errors from stage 1 cause status code ``400 Bad Request`` (regardless of the
+exact reason(s) which may vary across bulk parts), and errors from stage 2
+cause status code ``422 Unprocessable Entity``.
 
 
 Notes