Error Responses

Schema can be found here.

This section provides reference information about a common error format and recommended error codes[1] and process.   Figure 1 shows a generic synchronous web-service call with either a fault response or a message response (but not both).

Figure 1

REST Error Responses

When there is an error, the header information contains:

• Content-Type: application/xml
• An appropriate 3xx, 4xx, or 5xx HTTP status code

The body or the response also contains information about the error. The following sample error response shows the structure of response elements common to all REST error responses.

<?xml version="1.0" encoding="UTF-8"?>
<Error>
  <Code>NoSuchKey</Code>
  <Message>The resource you requested does not exist</Message>
  <Key>
    <Id>123456</Id>
  </Key>
  <RequestId>4442587FB7D0A2F9</RequestId>
</Error>

A detailed composite key with URI references is shown below.  The namespace is optional in REST depending on validation techniques.

<?xml version="1.0" encoding="UTF-8"?>
<Error xmlns="http://api.taybiz.com/core">
  <Code>NoSuchKey</Code>
  <Message>The resource you requested does not exist</Message>
  <Key>
    <Id uriRef="http://www.whatever.com/MAXIMOv6/PR#ORGID">TAYBIZ</Id>
    <Id uriRef="http://www.whatever.com/MAXIMOv6/PR#SITEID">COLORADO</Id>
    <Id uriRef="http://www.whatever.com/MAXIMOv6/PR#PRNUM">123456</Id>
  </Key>
  <RequestId>4442587FB7D0A2F9</RequestId>
</Error>

The following table explains the REST error response elements
[table]
Name,Description
Error,”Container for all error elements.”
Error/Code,”The error code is a required string that uniquely identifies an error condition. It is meant to be read and understood by programs that detect and handle errors by type. For more information, see List of Error Codes.Type: String”
Error/Message,”The error message contains a generic description of the error condition in English. It is intended for a human audience. Simple programs display the message directly to the end user if they encounter an error condition they don’t know how or don’t care to handle. Sophisticated programs with more exhaustive error handling and proper internationalization are more likely to ignore the error message.Type: String”
Error/Key,Container for Key information that identifies the resource or object that is involved in the error.
Error/Key/*Id,”The Id contains a piece of information to connect the subject of the error to the messaging system, GUI, or logging system. A Key has at least one Id and can have many to support spanning or composite keys.Type: String”
Error/Key/*Id/@uriRef,”An optional URI used to differentiate Id values.”
Error/RequestId,”An optional identifier that ties the request and error to the system that threw the error. This is often a GUID or UUID.Type: String”

[/table]
Many error responses contain additional structured data meant to be read and understood by a developer diagnosing programming errors. For example, if you send a Content-MD5 header with a REST PUT request that doesn’t match the digest calculated on the server, you receive a BadDigest error. The error response also includes as detail elements the digest we calculated, and the digest you told us to expect. During development, you can use this information to diagnose the error. In production, a well-behaved program might include this information in its error log.

SOAP Error Responses

In SOAP, an error result is returned to the client as a SOAP fault, with the HTTP response code 500. If you do not receive a SOAP fault, then your request was successful. The SOAP fault code is comprised of a standard SOAP 1.1 fault code (either “Server” or “Client”) concatenated with the organization-specific error code. For example: “Server.InternalError” or “Client.NoSuchResource”. The SOAP fault string element contains a generic, human readable error message in English. Finally, the SOAP fault detail element contains miscellaneous information relevant to the error.

For example, if you attempt to delete an object which does not exist, the body of the SOAP response contains a “NoSuchKey” SOAP fault.

The following example shows a sample SOAP error response.

<soapenv:Body>
  <soapenv:Fault>
    <Faultcode>soapenv:Client.NoSuchKey</Faultcode>
    <Faultstring>The specified resource does not exist.</Faultstring>
    <Detail>
      <Error xmlns="http://api.taybiz.com/core">
        <Code>NoSuchKey</Code>
        <Message>The resource you requested does not exist</Message>
        <Key>
         <Id uriRef="http://www.whatever.com/MAXIMOv6/PR#ORGID">TAYBIZ</Id>
         <Id uriRef="http://www.whatever.com/MAXIMOv6/PR#SITEID">COLORADO</Id>
         <Id uriRef="http://www.whatever.com/MAXIMOv6/PR#PRNUM">123456</Id>
        </Key>
        <RequestId>4442587FB7D0A2F9</RequestId>
      </Error>
    </Detail>
  </soapenv:Fault>
</soapenv:Body>

The following table explains the SOAP error response elements

[table]
Name,Description
Body/Fault,”Container for error information.”
Body/Fault/Faultcode,”The fault code is a string that uniquely identifies an error condition. It is meant to be read and understood by programs that detect and handle errors by type. For more information, see List of Error Codes.”
Body/Fault/Faultstring,”The fault string contains a generic description of the error condition in English. It is intended for a human audience. Simple programs display the message directly to the end user if they encounter an error condition they don’t know how or don’t care to handle. Sophisticated programs with more exhaustive error handling and proper internationalization are more likely to ignore the fault string.”
Body/Fault/Detail,”Container for the key involved in the error”
Body/Fault/Detail/*Error,”Identifies the information involved in the error; see the REST interface Error object for definition. The Fault element allows for an unbounded list of elements; a single error is expected. If many are sent agree on a limit to keep this payload small.”
[/table]

The following table lists generic error codes.  Custom application should use process-specific codes; however, do not overwrite or redefine these below.

List of Error Codes

[table]
HTTP Status Code[2],”Error Code”,”Description”,”SOAP Fault Code Prefix”
“301 Moved Permanently”,”PermanentRedirect”,”The resource you are attempting to access must be addressed using the specified endpoint. Please send all future requests to this endpoint.”,”Client”
“307 Moved Temporarily”,”Redirect”,”Temporary redirect.”,”Client”
“400 Bad Request”,”BadDigest”,”The Content-MD5 you specified did not match what we received.”,”Client”
“400 Bad Request”,”CredentialsNotSupported”,”This request does not support credentials.”,”Client”
“400 Bad Request”,”EntityTooLarge”,”Your proposed upload exceeds the maximum allowed object size.”,”Client”
“400 Bad Request”,”EntityTooSmall”,”Your proposed upload is smaller than the minimum allowed object size.”,”Client”
“400 Bad Request”,”ExpiredToken”,”The provided token has expired.”,”Client”
“400 Bad Request”,”IncompleteBody”,”You did not provide the number of bytes specified by the Content-Length HTTP header”,”Client”
“400 Bad Request”,”IncorrectNumberOfFilesInPostRequest”,”POST requires exactly one file upload per request.”,”Client”
“400 Bad Request”,”InlineDataTooLarge”,”Inline data exceeds the maximum allowed size.”,”Client”
“400 Bad Request”,”InvalidArgument”,”Invalid Argument”,”Client”
“400 Bad Request”,”InvalidResourceName”,”The specified resource is not valid.”,”Client”
“400 Bad Request”,”InvalidDigest”,”The Content-MD5 you specified was an invalid.”,”Client”
“400 Bad Request”,”InvalidRequest”,”SOAP requests must be made over an HTTPS connection.”,”Client”
“400 Bad Request”,”InvalidSOAPRequest”,”The SOAP request body is invalid.”,”Client”
“400 Bad Request”,”InvalidToken”,”The provided token is malformed or otherwise invalid.”,”Client”
“400 Bad Request”,”InvalidURI”,”Couldn’t parse the specified URI.”,”Client”
“400 Bad Request”,”MalformedError”,”The XML you provided was not well-formed or did not validate against our published schema.”,”Client”
“400 Bad Request”,”MalformedPOSTRequest”,”The body of your POST request is not well-formed multipart/form-data.”,”Client”
“400 Bad Request”,”MalformedXML”,”This happens when the user sends a malformed xml (xml that doesn’t conform to the published xsd) for the configuration. The error message is, “The XML you provided was not well-formed or did not validate against our published schema.””,”Client”
“400 Bad Request”,”MaxMessageLengthExceeded”,”Your request was too big.”,”Client”
“400 Bad Request”,”MaxPostPreDataLengthExceededError”,”Your POST request fields preceding the upload file were too large.”,”Client”
“400 Bad Request”,”MetadataTooLarge”,”Your metadata headers exceed the maximum allowed metadata size.”,”Client”
“400 Bad Request”,”MissingRequestBodyError”,”This happens when the user sends an empty xml document as a request. The error message is, “Request body is empty.””,”Client”
“400 Bad Request”,”MissingSecurityElement”,”The SOAP 1.1 request is missing a security element.”,”Client”
“400 Bad Request”,”MissingSecurityHeader”,”Your request was missing a required header.”,”Client”
“400 Bad Request”,”RequestIsNotMultiPartContent”,”Resource POST must be of the enclosure-type multipart/form-data.”,”Client”
“400 Bad Request”,”RequestTimeout”,”Your socket connection to the server was not read from or written to within the timeout period.”,”Client”
“400 Bad Request”,”TokenRefreshRequired”,”The provided token must be refreshed.”,”Client”
“400 Bad Request”,”UnexpectedContent”,”This request does not support content.”,”Client”
“403 Forbidden”,”AccessDenied”,”Access Denied”,”Client”
“403 Forbidden”,”AccountProblem”,”There is a problem with your account that prevents the operation from completing successfully.”,”Client”
“403 Forbidden”,”InvalidAccessKey”,”The Access Key you provided does not exist in our records.”,”Client”
“403 Forbidden”,”InvalidObjectState”,”The operation is not valid for the current state of the object.”,”Client”
“403 Forbidden”,”InvalidPayer”,”All access to this object has been disabled.”,”Client”
“403 Forbidden”,”InvalidSecurity”,”The provided security credentials are not valid.”,”Client”
“403 Forbidden”,”NotSignedUp”,”Your account is not signed up for the service.”,”Client”
“403 Forbidden”,”RequestTimeTooSkewed”,”The difference between the request time and the server’s time is too large.”,”Client”
“403 Forbidden”,”SignatureDoesNotMatch”,”The request signature we calculated does not match the signature you provided. Check your signing method.”,”Client”
“404 Not Found”,”NoSuchResource”,”The specified resource does not exist.”,”Client”
“404 Not Found”,”NoSuchKey”,”The specified key does not exist.”,”Client”
“404 Not Found”,”NoSuchUpload”,”The specified multipart upload does not exist. The upload ID might be invalid, or the multipart upload might have been aborted or completed.”,”Client”
“405 Method Not Allowed”,”MethodNotAllowed”,”The specified method is not allowed against this resource.”,”Client”
“409 Conflict”,”ResourceAlreadyExists”,”The requested resource name is not available. Please select a different name and try again.”,”Client”
“409 Conflict”,”ResourceNotEmpty”,”The resource you tried to delete is not empty.”,”Client”
“409 Conflict”,”InvalidResourceState”,”The request is not valid with the current state of the resource.”,”Client”
“409 Conflict”,”OperationAborted”,”A conflicting conditional operation is currently in progress against this resource. Please try again.”,”Client”
“411 Length Required”,”MissingContentLength”,”You must provide the Content-Length HTTP header.”,”Client”
“412 Precondition Failed”,”PreconditionFailed”,”At least one of the preconditions you specified did not hold.”,”Client”
“416 Requested Range Not Satisfiable”,”InvalidRange”,”The requested range cannot be satisfied.”,”Client”
“429 Too Many Requests”,”SlowDownClient”,”Please reduce your request rate.”,”Client”
“500 Internal Server Error”,”InternalError”,”We encountered an internal error. Please try again.”,”Server”
“501 Not Implemented”,”NotImplemented”,”A header you provided implies functionality that is not implemented.”,”Server”
“503 Service Unavailable”,”ServiceUnavailable”,”Please reduce your request rate.”,”Server”
“503 Slow Down”,”SlowDownServer”,”Please reduce your request rate.”,”Server”
[/table]

[1] Heavily influenced by Amazon Web-Services.

[2] HTTP Status codes from Wikipedia, 6/27/2013: http://en.wikipedia.org/wiki/List_of_HTTP_status_codes

[3] http://www.oracle.com/technetwork/articles/soa/luttikhuizen-fault-handling-1-1877036.html (not directly referenced but a good general read)