1.10.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.

<?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>

{
    "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 1.3. Fault Elements and Error Codes

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

{
    "itemNotFound" : {
        "code" : 404,
        "message" : "Not Found",
        "details" : "Error Details..."
    }
}

<?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>

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 retryAfter attribute that contains the content of the Retry-After header in XML Schema 1.0 date/time format.

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

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