Faults

hen an error occurs, the Rackspace Cloud DNS service returns a fault object containing an HTTP error response code that denotes 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 with their associated error codes and descriptions.

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

dnsFault has the structure and elements shown below. All other fault types extend dnsFault. Currently only fault types badRequest and deleteFault actually add additional elements to their structure as compared to the parent dnsFault. These two fault types are described later.

Example: Fault response: XML

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

<dnsFault xmlns="http://docs.rackspacecloud.com/dns/api/v1.0" code="500">
     <message>Main fault</message>
     <details>Error Details</details>
</dnsFault>

Example: Fault response: JSON

{  
  "message" : "Main fault",  
  "code" : 500,  
  "details" : "Error Details"  
}

The error code (code) is returned in the body of the response for convenience. The message element returns a human-readable message that is appropriate for display to the end user. The details element is optional and may contain information that is useful for tracking down an error, such as a stack trace. The details element may or may not be appropriate for display to an end user, depending on the role and experience of the end user.

The fault’s root element (for example, dnsFault) may change depending on the type of error. badRequest fault adds a validationErrors element that contains a list of error messages for invalid requests. The first two badRequest examples show errors when the request structure is wrong:

Example: badRequest fault on request structure errors: XML

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

<badRequest xmlns="http://docs.rackspacecloud.com/dns/api/v1.0" code="400">
     <message>The request could not be processed.</message>
     <details> Unexpected close tag </domains> expected </domain>.
     </details>
</badRequest>

Example: badRequest fault on request structure errors: JSON

{  
  "message":"The request could not be processed.",  
  "code":400,  
  "details":"Unexpected close tag </domains>; expected </domain>."  
}

The next two badRequest examples show validation errors:

Example: badRequest fault on validation errors: XML response

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

<badRequest xmlns="http://docs.rackspacecloud.com/dns/api/v1.0" code="400">
     <validationErrors>
          <messages>Must provide a name for each domain.</messages>
          <messages>null is not a valid domain name.</messages>
     </validationErrors>
</badRequest>

Example: badRequest fault on validation errors: JSON response

{  
  "validationErrors":  
  {  
    "messages":  
    [  
      "Must provide a name for each domain.",  
      "null is not a valid domain name."  
    ]  
  },  
  "code":400  
}

deleteFault adds a failedItems element that contains details on entities that could not be deleted:

Example: Example deleteFault: XML

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

<deleteFault xmlns="http://docs.rackspacecloud.com/dns/api/v1.0" code="500">
     <message>One or more items could not be deleted.</message>
     <details>See errors list for details.</details>
     <failedItems>
          <fault code="503">
               <message>The DNS API is currently not available.</message>
               <details>Domain ID: 123</details>
          </fault>
     </failedItems>
</deleteFault>

Example: deleteFault: JSON

{  
    "failedItems":  
     {  
        "faults":  
         [  
          {  
            "message":"The DNS API is currently not available.",  
            "code":503,  
            "details":"Domain ID: 123"  
          }  
         ]  
     },  
     "message":"One or more items could not be deleted.",  
     "code":500,  
     "details":"See errors list for details."  
}