3.6. Faults

When an error occurs, the Cloud Authentication Service will return an HTTP error response code denoting the type of error. In the body of the response, the system will return additional information about the fault.

The following table lists possible fault types along with their associated error codes.

Table 3.3. Fault Types
Fault Element Associated Error Code Expected in All Requests
authFault 500, 400, others YES
serviceUnavailable 503 YES
unauthorized 401 YES
badRequest 400 YES
overLimit 413 YES
userDisabled 403
forbidden 403
itemNotFound 404
usernameConflict 409

From an XML schema perspective, all API faults are extensions of the base fault type, AuthFault. When working with a system such as JAXB that binds XML to actual classes, AuthFault can be used as a catch-all if there's no interest in distinguishing between individual fault types.


Example 3.9. Fault Response: XML

<?xml version="1.0" encoding="UTF-8"?>

<authFault xmlns="http://docs.rackspacecloud.com/auth/api/v1.1"
    <details>Error Details...</details>



Example 3.10. Fault Response: JSON

    "authFault" : {
        "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, such as a stack trace, useful for tracking down an error. The detail section may or may not be appropriate for display to an end user.

The fault's root element (for example, authFault) may change depending on the type of error.

The following are examples of an itemNotFound error.


Example 3.11. Not Found Fault: XML

<?xml version="1.0" encoding="UTF-8"?>

<itemNotFound xmlns="http://docs.rackspacecloud.com/auth/api/v1.1"
    <message>Item not found!</message>
    <details>Error Details...</details>



Example 3.12. Not Found Fault: JSON

    "itemNotFound" : {
        "code" : 404,
        "message" : "Item not found!",
        "details" : "Error Details..."