Specification modified to include changes in error responses

spec/README.md

@@ -135,10 +135,10 @@ whole lifetime of the server.
   * The HTTP status code (e.g., `400`, which is a bad request).  The target
     audience of this information is the client code.  The client can thus use
     this information to control the program flow.
-  * The HTTP reason phrase.  The target audience in this case is the human
-    operating the client.  The human can use this information to make a
-    decision on how to proceed.
-  * The body is optional
+  * The body is optional depending on the request method and the status code.  For
+    error responses (4xx and 5xx) a json body is included with a reason phrase.
+    The target audience in this case is the human operating the client.  The
+    human can use this information to make a decision on how to proceed.
 * All successful API calls will return a representation of the *final* state
   attained by the objects which have been addressed (either requested, set or
   deleted).
@@ -168,6 +168,15 @@ Content-Length: 189
 ]
 ```
 
+While an error response may look like this:
+```http
+404 Not Found
+Content-Type: application/json
+Content-Length: 25
+
+{"reason": "Not Found"}
+```
+
 
 ## API Elements
 
@@ -247,8 +256,8 @@ A new id is created for the appended route so it can be referenced later.
     }
     ```
 * **Error Responses**:
-  * **Code**: `400 Malformed JSON`
-  * **Code**: `422 Invalid Route`
+  * **Code**: `400`; **Reason**: `Malformed JSON`
+  * **Code**: `422`; **Reason**: `Invalid Route`
 * **Sample Call**:<br />
     ```sh
     $ curl -X POST --data-binary @- $KAPOW_URL/routes <<EOF
@@ -300,8 +309,8 @@ A new id is created for the appended route so it can be referenced later.
     }
     ```
 * **Error Responses**:
-  * **Code**: `400 Malformed JSON`
-  * **Code**: `422 Invalid Route`
+  * **Code**: `400`; Reason: `Malformed JSON`
+  * **Code**: `422`; Reason: `Invalid Route`
 * **Sample Call**:<br />
     ```sh
     $ curl -X PUT --data-binary @- $KAPOW_URL/routes <<EOF`
@@ -334,7 +343,7 @@ Removes the route identified by `{id}`.
 * **Success Responses**:
   * **Code**: `204 No Content`
 * **Error Responses**:
-  * **Code**: `404 Not Found`
+  * **Code**: `404`; Reason: `Route Not Found`
 * **Sample Call**:<br />
   ```sh
   $ curl -X DELETE $KAPOW_URL/routes/ROUTE_1f186c92_f906_4506_9788_a1f541b11d0f
@@ -362,7 +371,7 @@ Retrieves the information about the route identified by `{id}`.
     }
     ```
 * **Error Responses**:
-  * **Code**: `404 Not Found`
+  * **Code**: `404`; Reason: `Route Not Found`
 * **Sample Call**:<br />
   ```sh
   $ curl -X GET $KAPOW_URL/routes/ROUTE_1f186c92_f906_4506_9788_a1f541b11d0f
@@ -390,8 +399,10 @@ response.
     operating the client.  The human can use this information to make a
     decision on how to proceed.
 * Regarding HTTP request and response bodies:
-  * The response body will be empty in case of error.
-  * It will transport binary data in other case.
+  * In case of error the response body will be a json entity containing a reason
+    phrase.  The target audience in this case is the human operating the client.
+    The human can use this information to make a decision on how to proceed.
+  * It will transport binary data in any other case.
 * When several error conditions can happen at the same time, the order of the
   checks is implementation-defined.
 
@@ -518,11 +529,11 @@ path doesn't exist or is invalid.
     **Header**: `Content-Type: application/octet-stream`<br />
     **Content**: The value of the resource.  Note that it may be empty.
 * **Error Responses**:
-  * **Code**: `400 Invalid Resource Path`<br />
+  * **Code**: `400`; Reason: `Invalid Resource Path`<br />
     **Notes**: Check the list of valid resource paths at the top of this section.
-  * **Code**: `404 Handler ID Not Found`<br />
+  * **Code**: `404`; Reason: `Handler ID Not Found`<br />
     **Notes**: Refers to the handler resource itself.
-  * **Code**: `404 Resource Item Not Found`<br />
+  * **Code**: `404`; Reason: `Resource Item Not Found`<br />
     **Notes**: Refers to the named item in the corresponding data API resource.
 * **Sample Call**:<br />
   ```sh
@@ -541,9 +552,9 @@ path doesn't exist or is invalid.
 * **Success Responses**:
   * **Code**: `200 OK`
 * **Error Responses**:
-  * **Code**: `400 Invalid Resource Path`<br />
+  * **Code**: `400`; Reason: `Invalid Resource Path`<br />
     **Notes**: Check the list of valid resource paths at the top of this section.
-  * **Code**: `404 Handler ID Not Found`<br />
+  * **Code**: `404`; Reason: `Handler ID Not Found`<br />
     **Notes**: Refers to the handler resource itself.
 * **Sample Call**:<br />
   ```sh