document error handling

1 files changed, 33 insertions, 23 deletions

diff --git a/doc/sphinx/reducer.rst b/doc/sphinx/reducer.rst
index defd088..d1dc0f5 100644
--- a/doc/sphinx/reducer.rst
+++ b/doc/sphinx/reducer.rst
@@ -89,13 +89,23 @@ above would look like following for the transition action_ ``select_continent``:
     ]
   }
 
+An action may also result into an *error response* instead of a new state.
+Clients should then render this error response to the user and allow the user
+to continue from the old state.  An error response looks like this:
+
+.. code-block:: json
+
+  {
+    "code": 123,
+    "hint": "something went wrong",
+    "details": "parameter foo failed to frobnify"
+  }
+
 States
 ^^^^^^
 
 Overall, the reducer knows the following states:
 
-  - **ERROR**: The transition led to an error. No further transitions are possible from
-               this state, but the client may want to continue from a previous state.
   - **CONTINENT_SELECTING**: The user should specify the continent where they are living,
                so that we can show a list of countries to choose from.
   - **COUNTRY_SELECTING**: The user should specify the country where they are living,
@@ -607,16 +617,18 @@ to it:
     }
 
 If required attributes are missing, do not match the required regular
-expression, or fail the custom validation logic, the reducer SHOULD transition
-to an error state indicating what was wrong about the input.  A reducer that
-does not support some specific validation logic MAY accept the invalid input
-and proceed anyway.  The error state will include a Taler error code that
-is specific to the failure, and optional details.  Example:
+expression, or fail the custom validation logic, the reducer SHOULD return an
+error response indicating that the transition has failed and what is wrong about
+the input and not transition to a new state.  A reducer that does not support
+some specific validation logic MAY accept the invalid input and proceed anyway.
+The error state will include a Taler error code that is specific to the
+failure, and optional details.
+
+Example:
 
 .. code-block:: json
 
     {
-      "backup_state": "ERROR",
       "code": 8404,
       "hint": "An input did not match the regular expression.",
       "detail": "social_security_number"
@@ -709,8 +721,8 @@ response:
       ]
     }
 
-If the index is invalid, the reducer will instead
-transition into an ``ERROR`` state.
+If the index is invalid, the reducer will return an error
+response instead of making a transition.
 
 
 **next** (from ``AUTHENTICATIONS_EDITING``):
@@ -785,8 +797,8 @@ policy.  The ``methods`` array specifies the index of the
 ``authentication_method`` in the ``authentication_methods`` array, as well as
 the provider that was selected to supervise this authentication.
 
-If no authentication method was provided, the reducer will transition into an
-``ERROR`` state instead of suggesting policies.
+If no authentication method was provided, the reducer will
+return an error response instead of making a transition.
 
 
 **add_policy**:
@@ -873,7 +885,7 @@ the "policies" array, returning an updated state:
 
 If the new policy is invalid, for example because it adds an unknown
 authentication method, or the selected provider does not support the type of
-authentication, the reducer will transition into an ``ERROR`` state instead of
+authentication, the reducer return an error response instead of
 adding the new policy.
 
 
@@ -904,7 +916,7 @@ An example for a possible argument would thus be:
 
 If the new policy is invalid, for example because it adds an unknown
 authentication method, or the selected provider does not support the type of
-authentication, the reducer will transition into an ``ERROR`` state instead of
+authentication, the reducer will return an error response instead of
 modifying the policy.
 
 
@@ -967,7 +979,7 @@ be:
       ]
     }
 
-If the index given is invalid, the reducer will transition into an ``ERROR`` state
+If the index given is invalid, the reducer will return an error response
 instead of deleting a policy.
 
 
@@ -1028,7 +1040,7 @@ be:
       ]
     }
 
-If the index given is invalid, the reducer will transition into an ``ERROR`` state
+If the index given is invalid, the reducer will return an error response
 instead of deleting a challenge.
 
 
@@ -1052,8 +1064,8 @@ given policy expiration time. This is an array because fees could
 be in different currencies.  The final cost may be lower if the
 user already paid for some of the time.
 
-If the array of ``policies`` is currently empty, the reducer will transition
-into an ``ERROR`` state instead of allowing the user to continue.
+If the array of ``policies`` is currently empty, the reducer will
+return an error response instead of allowing the user to continue.
 
 
 **enter_secret:**
@@ -1158,8 +1170,8 @@ Using this transition, the user confirms that the secret and expiration
 settings in the current state are acceptable. The transition does not take any
 arguments.
 
-If the secret is currently empty, the reducer will transition into an
-``ERROR`` state instead of allowing the user to continue.
+If the secret is currently empty, the reducer will return an
+error response instead of allowing the user to continue.
 
 After adding a secret, the reducer may transition into different states
 depending on whether payment(s) are necessary.  If payments are needed, the
@@ -1236,14 +1248,13 @@ will wait this long before giving up.  If no timeout is given, the check is
 done as quickly as possible without additional delays.  The reducer will continue
 to either an updated state with the remaining payment requests, to the
 ``BACKUP_FINISHED`` state (if all payments have been completed and the backup
-finished), or into an ``ERROR`` state in case there was an irrecoverable error,
+finished), or return an error response in case there was an irrecoverable error,
 indicating the specific provider and how it failed.  An example for this
 final error state would be:
 
 .. code-block:: json
 
     {
-      "backup_state": "ERROR",
       "http_status" : 500,
       "upload_status" : 52,
       "provider_url" : "https://bad.example.com/",
@@ -1359,7 +1370,6 @@ message together with a transition failure:
 .. code-block:: json
 
     {
-      "recovery_state": "ERROR",
       "error_message": "account unknown to Anastasis server",
       "error_code": 9,
     }