 | Feedback |  |
In response to a request, the Amazon Associates Web Service web service returns an XML document that contains the results of the call in an XML data structure. This data conforms to a WSDL and schema.
For REST requests, this data structure is simply the body of the HTTP response. You can use a data binding method for REST responses, or use an XML parser directly to process the information.
For SOAP requests, the data structure is the SOAP message body of the response. SOAP toolkits typically convert the response data into structures for use with your programming language, or allow you to specify your own data bindings.
Other than the use of a message envelope in the SOAP response, REST and SOAP responses are identical. Both conform to the Amazon Associates Web Service schema. The SOAP WSDL imports an XSD file to define the response messages. REST users can access the XSD file directly. For more information, see WSDL Location.
Amazon Associates Web Service responses vary according to the operations and parameters submitted in the request. There are, however, segments of the response that are common across all responses, as shown in the following figure.
The following sections describe each segment in this response.
The first two lines of every response contain version information. The first line details the XML version used, which, in this example, is 1.0. The first line also includes the character encoding, which, in this example, is UTF-8.
The second line of every response contains the name of the response, which is
named after the operation in the request. In this example, the ItemLookup operation returns a response element named ItemLookupResponse
The second line also contains the version of Amazon Associates Web Service used to create the response. In this example, the version number is 2006-09-13. If a version is not specified in a request, Amazon Associates Web Service uses the default version, 2005-10-05. Make sure to specify the latest version number if you want the latest Amazon Associates Web Service functionality.
The second segment of a response is always the Operation Request. For the most part, it returns the operation's parameters, called arguments, that were used in the request. There is, however, some additional information. The first large subsection is the HTTPHeader section, which specifies the network agent used to send the request. Typically, the agent, called the user agent, is a web browser and the information returned describes that browser, such as its name, version, and the operating system of its host.
The second large subsection contains the arguments, or operation parameters, used in the request. These values are unprocessed echoes of the values submitted in the request. This information is echoed for the benefit of troubleshooting requests.
Finally, interspersed around the large subsections in the Operation Request segment is Amazon Associates Web Service processing information, including the Request ID and the time it took to process the request. This is interesting information for troubleshooting. You will not, however, have to use either the Request ID or the processing time in future requests.
The segments described so far are typically less interesting than the ones that follow. The Request Validation segment contains error information if there was an error in the request. It is also the last segment that Amazon Associates Web Service returns in a response if there was an error.
In the preceding example, the request was valid, as shown in the IsValid element:
<IsValid>True</IsValid>
The IsValid element pertains only to the validity of the request. It reports whether all of the required elements of a request are present, whether parameter restrictions and constraints have been obeyed, and whether parameter values are legal. IsValid does not assure that a valid request will be processed by Amazon Associates Web Service. For example, an ItemId, such as, 1234ABCD, is in the correct form, but no items in Amazon's catalog match that ItemId, so, the request would be valid but would return an error.
There are many reasons why a request can fail, as described in the following table.
| Problem | Description |
|---|---|
| Incorrect parameters supplied |
The request is missing parameters that an operation requires, or the combination of parameters is not allowed, or the Service parameter was omitted. In this case, the IsValid value is "False" and the request is not processed by Amazon Associates Web Service. Common mistakes that cause these errors are spaces in the URL that prevent Amazon Associates Web Service from reading the entire request, or misspelled and mis-capitalized parameter names or values. If you inadvertently enter a space in a request, your browser automatically enters the URL-encoded form of a space: %20. For example, if you paste, ItemId= B12345, into your browser as part of a request, the URL field in the browser shows, ItemId=%20B12345. |
| Invalid values |
The request might be syntactically correct but the values for one or more parameters might be invalid. For example, you might supply an ItemId value that does not match any item sold on Amazon. In this case, the IsValid value is "True" but an error message is returned that says that the value is "not a valid value for ItemId. Please change this value and retry your request." |
| Empty result |
The request is valid but there is no data that matches the search criteria. In this case, the IsValid value is "True." Remember that parameter names and values are case sensitive. |
| Network or processing error |
The request is valid but a network outage or processing failure has caused Amazon Associates Web Service to return an empty response. In this case, the IsValid value is "True." |
| Partial request errors | Amazon Associates Web Service returns as much information as possible. For example, if you use a batch request and Amazon Associates Web Service finds items for one request but not the other, Amazon Associates Web Service returns all of the information for the found item and an error message for the other request. |
When one of these errors occurs, the IsValid value is False and Amazon Associates Web Service returns an error element in the Request Validation segment. The error element includes:
Error code—The title of the error.
Error message—A brief description of the error condition.
The following example shows an error message.
<Errors>
<Error>
<Code>missing_service_parameter</code>
<message>Your request is missing the Service parameter. Please add the Service parameter to your request and retry. Valid values for the Service parameter include AWSEcommerceService.</message>
</Error>
</Errors>The more difficult error to assess is a request that is valid, that is processed, but contains an error in logic. For example, a request might use default values such that only items in new condition are returned when the requester meant to return items in all conditions.
The remainder of the Request Validation segment is a subsection named after the
operation used in the request. In this example, the subsection is named ItemLookupRequest. This subsection echoes the parameter values used
in the request. These values are returned for the purpose of troubleshooting the
request.
Assuming that your request is valid, the final segment of the response that contains the item attributes is typically the part of the response that contains the most value. This segment contains all of the descriptive information about the items that satisfied the request. In the preceding example, one item was found that satisfied the search criteria. Many attributes are returned that describe that item, including, the title, "Saving Miss Oliver's: A Novel of Leadership, Loyalty and Change."
The item attributes returned in a response vary according to the response group used and the items found. Merchants do not always provide Amazon with a single set of item attributes. For example, one merchant might supply the name of a book's publisher, another might not. A response contain both of these books would therefore contain a different set of item attributes. Item attributes that do not have values are not returned. The API Reference Guide describes the item attributes that can be returned by each response group.
