When an error occurs, the system will return an HTTP error response code denoting the type of error. The system will also return additional information about the fault in the body of the response.
Example 3.14. Fault Response: XML
<cloudServersFault xmlns="http://docs.rackspacecloud.com/servers/api/v1.0" code="500">
<message>Fault!</message>
<details>Error Details...</details>
</cloudServersFault>
Example 3.15. Fault Response: JSON
{
"cloudServersFault" : {
"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 may or may not be appropriate for display to an end user.
The root element of the fault (e.g. cloudServersFault) may change depending on the type of error. The following is a list of possible elements along with their associated error codes.
| Fault Element | Associated Error Codes | Expected in All Requests? |
| cloudServersFault | 500, 400, other codes possible |  |
| serviceUnavailable | 503 | |
| unauthorized | 401 | |
| badRequest | 400 | |
| overLimit | 413 | |
| badMediaType | 415 | |
| badMethod | 405 | |
| itemNotFound | 404 | |
| buildInProgress | 409 | |
| serverCapacityUnavailable | 503 | |
| backupOrResizeInProgress | 409 | |
| resizeNotAllowed | 403 | |
| notImplemented | 501 |
Example 3.16. Fault Response, Item Not Found: XML
<itemNotFound xmlns="http://docs.rackspacecloud.com/servers/api/v1.0" code="404">
<message>Not Found</message>
<details>Error Details...</details>
</itemNotFound>
Example 3.17. Fault Response, Item Not Found: JSON
{
"itemNotFound" : {
"code" : 404,
"message" : "Not Found",
"details" : "Error Details..."
}
}
From an XML schema perspective, all API faults are extensions of the base fault type CloudServersAPIFault. When working with a system that binds XML to actual classes (such as JAXB), one should be capable of using CloudServersAPIFault as a “catch-all” if there's no interest in distinguishing between individual fault types.
The OverLimit fault is generated when a rate limit threshold is exceeded. For convenience, the fault adds a replyAfter attribute that contains the content of the Reply-After header in XML Schema 1.0 date/time format.
Example 3.18. Fault Response, Over Limit: XML
<overLimit xmlns="http://docs.rackspacecloud.com/servers/api/v1.0" code="413"
retryAfter="2010-08-01T00:00:00Z">
<message>OverLimit Retry...</message>
<details>Error Details...</details>
</overLimit>
Example 3.19. Fault Response, Over Limit: JSON
{
"overLimit" : {
"code" : 413,
"message" : "OverLimit Retry...",
"details" : "Error Details...",
"retryAfter" : "2010-08-01T00:00:00Z"
}
}
