docs: update the API faults concept guide

This updates the API concept guide to talk about request-ids
and the Server Actions API, while keeping the existing content
on sync and async errors.

blueprint complete-todo-in-api-concept-doc

Change-Id: Icbc4a3a3559552f7d210838536897e411a9d4ce4

1 files changed, 65 insertions, 75 deletions

diff --git a/api-guide/source/faults.rst b/api-guide/source/faults.rst
index 3c269985f2..c2ccc754d0 100644
--- a/api-guide/source/faults.rst
+++ b/api-guide/source/faults.rst
@@ -2,114 +2,102 @@
 Faults
 ======
 
-Synchronous faults
-~~~~~~~~~~~~~~~~~~
+This doc looks at how to understand what has happened to your API request.
 
-When an error occurs at request time, the system also returns additional
-information about the fault in the body of the response.
-
-
-**Example: Fault: JSON response**
-
-.. code::
-
-    {
-       "computeFault":{
-          "code":500,
-          "message":"Fault!",
-          "details":"Error Details..."
-       }
-    }
+Every HTTP request has a status code. 2xx codes signify the API was a success.
+However, that is often not the end of the story. That generally only means the
+request to start the operation has been accepted, it does not mean the action
+you requested has successfully completed.
 
-The error code is returned in the body of the response for convenience.
-The message section returns a human-readable message that is appropriate
-for display to the end user. The details section is optional and may
-contain information—for example, a stack trace—to assist in tracking
-down an error. The detail section might or might not be appropriate for
-display to an end user.
 
-The root element of the fault (such as, computeFault) might change
-depending on the type of error. The following is a list of possible
-elements along with their associated error codes.
+Tracking Errors by Request ID
+==============================
 
-Fault elements and error codes
-------------------------------
+Every request made has a unique Request ID.
+This is returned in a response header.
+Here is an example response header:
 
--  ``computeFault``: 500, 400, other codes possible
+X-Compute-Request-ID: req-4b9e5c04-c40f-4b4f-960e-6ac0858dca6c
 
-- ``notImplemented``: 501
+Server Actions
+--------------
 
--  ``serverCapacityUnavailable``: 503
+There is an API for end users to list the outcome of Server Actions,
+referencing the requested action by request id.
 
-- ``serviceUnavailable``: 503
+For more details, please see:
+http://developer.openstack.org/api-ref-compute-v2.1.html#os-instance-actions-v2.1
 
-- ``badRequest``: 400
+Logs
+----
 
-- ``unauthorized``: 401
+All logs on the system, by default, include the request-id when available.
+This allows an administrator to track the API request processing as it
+transitions between all the different nova services.
 
-- ``forbidden``: 403
+Instance Faults
+---------------
 
-- ``resizeNotAllowed``: 403
+Nova often adds an instance fault DB entry for an exception that happens
+while processing an API request. This often includes more admin focused
+information, such as a stack trace.
+However, there is currently no API to retrieve this information.
 
-- ``itemNotFound``: 404
+Notifications
+-------------
 
-- ``badMethod``: 405
+In many cases there are also notifications emitted that describe the error.
+This is an administrator focused API, that works best when treated as
+structured logging.
 
-- ``backupOrResizeInProgress``: 409
 
-- ``buildInProgress``: 409
+Synchronous Faults
+==================
 
-- ``conflictingRequest``: 409
-
-- ``overLimit``: 413
+If an error occurs while processing our API request, you get a non 2xx
+API status code. The system also returns additional
+information about the fault in the body of the response.
 
-- ``badMediaType``: 415
 
-**Example: Item Not Found fault: JSON response**
+**Example: Fault: JSON response**
 
 .. code::
 
     {
-       "itemNotFound":{
-          "code":404,
-          "message":"Not Found",
+       "computeFault":{
+          "code":500,
+          "message":"Fault!",
           "details":"Error Details..."
        }
     }
 
+The error code is returned in the body of the response for convenience.
+The message section returns a human-readable message that is appropriate
+for display to the end user. The details section is optional and may
+contain information—for example, a stack trace—to assist in tracking
+down an error. The detail section might or might not be appropriate for
+display to an end user.
 
-From an XML schema perspective, all API faults are extensions of the
-base ComputeAPIFault fault type. When working with a system that binds
-XML to actual classes (such as JAXB), you should use ComputeAPIFault as
-a catch-all if you do not want to distinguish between individual fault
-types.
-
-The OverLimit fault is generated when a rate limit threshold is
-exceeded. For convenience, the fault adds a retryAfter attribute that
-contains the content of the Retry-After header in XML Schema 1.0
-date/time format.
-
-
-**Example: Over Limit fault: JSON response**
-
-.. code::
-
-    {
-        "overLimit" : {
-            "code" : 413,
-            "message" : "OverLimit Retry...",
-            "details" : "Error Details...",
-            "retryAfter" : "2010-08-01T00:00:00Z"
-        }
-    }
+The root element of the fault (such as, computeFault) might change
+depending on the type of error. The following is a list of possible
+elements along with their associated error codes.
 
+For more information on possible error code, please see:
+http://specs.openstack.org/openstack/api-wg/guidelines/http.html#http-response-codes
 
 Asynchronous faults
-~~~~~~~~~~~~~~~~~~~
+===================
 
 An error may occur in the background while a server or image is being
-built or while a server is executing an action. In these cases, the
-server or image is placed in an ``ERROR`` state and the fault is
+built or while a server is executing an action.
+
+In these cases, the server or image is usually placed in an ``ERROR`` state.
+For some operations, like resize, its possible that the operations fails but
+the instance gracefully returned to its original state before attempting the
+operation. In both of these cases, you should be able to find out more from
+the Server Actions API described above.
+
+When a server or image is placed into an ``ERROR`` state, a fault is
 embedded in the offending server or image. Note that these asynchronous
 faults follow the same format as the synchronous ones. The fault
 contains an error code, a human readable message, and optional details
@@ -188,3 +176,5 @@ created timestamp that specify when the fault occurred.
             ]
         }
     }
+
+