DRAFT -  DRAFT -  DRAFT -  DRAFT -  DRAFT -  DRAFT -  DRAFT -  DRAFT - 

3.9.1. Synchronous Faults

When an error occurs at request time, 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.42. Fault Response: XML

<?xml version="1.0" encoding="UTF-8"?>
<computeFault
    xmlns="http://docs.openstack.org/compute/api/v1.1"
    code="500">
  <message>Fault!</message>
  <details>Error Details...</details>
</computeFault>

Example 3.43. Fault Response: JSON

{
    "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 may or may not be appropriate for display to an end user.

The root element of the fault (e.g. computeFault) may change depending on the type of error. The following is a list of possible elements along with their associated error codes.

Table 3.4. Fault Elements and Error Codes
Fault Element Associated Error Codes Expected in All Requests?
computeFault 500, 400, other codes possible
serviceUnavailable 503
unauthorized 401
forbidden 403
badRequest 400
overLimit 413
badMediaType 415
badMethod 405
itemNotFound 404
buildInProgress 409
serverCapacityUnavailable 503
backupOrResizeInProgress 409
resizeNotAllowed 403
notImplemented 501

Example 3.44. Fault Response, Item Not Found: XML

<?xml version="1.0" encoding="UTF-8"?>
<itemNotFound
    xmlns="http://docs.openstack.org/compute/api/v1.1"
    code="404">
  <message>Not Found</message>
  <details>Error Details...</details>
</itemNotFound>

Example 3.45. 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 ComputeAPIFault. When working with a system that binds XML to actual classes (such as JAXB), one should be capable of using ComputeAPIFault 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 retryAt attribute that contains the content of the Retry-After header in XML Schema 1.0 date/time format.

Example 3.46. Fault Response, Over Limit: XML

<?xml version="1.0" encoding="UTF-8"?>
<overLimit
    xmlns="http://docs.openstack.org/compute/api/v1.1"
    code="413"
    retryAt="2010-08-01T00:00:00Z">
  <message>OverLimit Retry...</message>
  <details>Error Details...</details>
</overLimit>

Example 3.47. Fault Response, Over Limit: JSON

{
    "overLimit" : {
        "code" : 413,
        "message" : "OverLimit Retry...",
        "details" : "Error Details...",
	    "retryAt" : "2010-08-01T00:00:00Z"
    }
}

Legal notices