YSM Technology Solutions Portal

Introduction

An EWS SOAP response that is returned by the EWS server contains an Envelope element with a Header element and a Body element:

   <?xml version='1.0' encoding='UTF-8'?>
   <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
   	xmlns:xsd="http://www.w3.org/2001/XMLSchema"
   	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   	xmlns="http://marketing.ews.yahooapis.com/V3">

      <soap:Header>
      ...
      </soap:Header>

      <soap:Body>
      ...
      </soap:Body>
   </soap:Envelope>

The header contains transaction information about the request, regardless of whether the request succeeded or failed. If the request was successful, the body will contain either the return elements and data, or the empty string (for those operations that do not return data). If the request was not successful, the body will contain an error code and error message.

Response SOAP Header

The SOAP header in the response contains elements that provide information about the response, the command group and your quota:

remainingQuota: The quota remaining for the command group.
quotaUsedForThisRequest: The quota deducted for this request. (If a system exception occurs during the request, no quota is deducted.)
commandGroup: The command group to which the operation belongs.
timeTakenMillis: How long the operation took to complete inside the service backend (excluding network latency).

   <?xml version='1.0' encoding='UTF-8'?>
   <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
   	xmlns:xsd="http://www.w3.org/2001/XMLSchema"
   	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   	xmlns="http://marketing.ews.yahooapis.com/V3">

      <soap:Header>
         <remainingQuota>9999974</remainingQuota>
         <quotaUsedForThisRequest>532</quotaUsedForThisRequest>
         <commandGroup>Marketing</commandGroup>
         <timeTakenMillis>2813</timeTakenMillis>
      </soap:Header>

      <soap:Body>
      ...
      </soap:Body>
   </soap:Envelope>

Tracking Quota

Your EWS license specifies your command groups and quota (see Command Groups and Quota). Each EWS request includes either an operation or list-based operation that counts against your quota (see Request SOAP Body). As noted, each EWS response includes three elements in the SOAP header; use the remainingQuota and commandGroup elements to track your quota consumption.

Response SOAP Body

The SOAP body in the response contains the response elements and data. For example, the response for the BasicReport getReportList operation might look like this:

   <?xml version='1.0' encoding='UTF-8'?>
   <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
   	xmlns:xsd="http://www.w3.org/2001/XMLSchema"
   	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   	xmlns="http://marketing.ews.yahooapis.com/V3">

      <soap:Header>
      ...
      </soap:Header>

      <soap:Body>
         <getReportListResponse>
            <out>
             <ReportInfo>
                  <createDate>2006-07-18T19:11:41.943-07:00</createDate>
                  <reportID>243</reportID>
                  <reportName>MultiChannelCampaign Report</reportName>
                  <status>COMPLETE</status>
             </ReportInfo>
             <ReportInfo>
                  <createDate>2006-07-18T19:08:48.394-07:00</createDate>
                  <reportID>242</reportID>
                  <reportName>MultiChannelMarketingActivity
                       Report</reportName>
                  <status>COMPLETE</status>
             </ReportInfo>
            </out>
         </getReportListResponse>
      </soap:Body>
   </soap:Envelope>

To capture errors for individual objects, some operations have responses that contain error elements as part of the response data. This is particularly useful for list-based operations that include multiple objects. (For example, see the CampaignResponse data object.) Given this, the response for the CampaignService addCampaigns operation might look like this:

   <?xml version='1.0' encoding='UTF-8'?>
   <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
   	xmlns:xsd="http://www.w3.org/2001/XMLSchema"
   	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   	xmlns="http://marketing.ews.yahooapis.com/V3">

      <soap:Header>
      ...
      </soap:Header>

      <soap:Body>
         <addCampaignsResponse>
            <out>
             <CampaignResponse>
               <campaign>
                  <ID>5354501</ID>
                  <accountID>9901673</accountID>
                  <advancedMatchON>true</advancedMatchON>
                  <campaignOptimizationON>false</campaignOptimizationON>
                  <contentMatchON>true</contentMatchON>
                  ...
               </campaign>
               <errors xsi:nil="true" />
               <operationSucceeded>true</operationSucceeded>
             </CampaignResponse>

             <CampaignResponse>
               <campaign>
                  <ID xsi:nil="true" />
                  <accountID>9901673</accountID>
                  <advancedMatchON>true</advancedMatchON>
                  <campaignOptimizationON>false</campaignOptimizationON>
                  <contentMatchON>true</contentMatchON>
                  ...
               </campaign>
               <errors>
                  <Error>
                     <code>E2012</code>
                     <message>Name exceeds maximum allowed length
                           of 50.</message>
                   </Error>
               </errors>
               <operationSucceeded>false</operationSucceeded>
             </CampaignResponse>
            </out>
         </addCampaignsResponse>
      </soap:Body>
   </soap:Envelope>

Empty Response

If an operation does not return any data, the SOAP body will contain an empty response element. For example, the response for the BasicReportService deleteReport operation would look like this:

   <?xml version='1.0' encoding='UTF-8'?>
   <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
   	xmlns:xsd="http://www.w3.org/2001/XMLSchema"
   	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   	xmlns="http://marketing.ews.yahooapis.com/V3">

      <soap:Header>
      ...
      </soap:Header>

      <soap:Body>
        <deleteReportResponse/>
      </soap:Body>
   </soap:Envelope>

List-Based Operations

List-based operations allow you to add, get, update, or delete multiple objects. When you set up a list-based operation, you list the objects in a specific order. EWS guarantees that the operation's response will maintain this order when the response objects are returned (see List-Based Operations for EWS Requests).

This is particularly important when you are working with add operations, such as addCampaigns or addAdGroups, which do not include the IDs as identifiers (because the objects have not yet been created).

For example, suppose you use the addAds operation to create three new ads. And, suppose that one of these ads has an error in it. Because the operation's response maintains your ordering, you will be able to identify which ad has the error: if the second ad contains the error then the second response object will indicate that the operation failed (operationSucceeded = false).

Lists of Elements

Lists of elements in the response are enclosed by a single element. For example, getCampaigns, which returns a list of Campaign elements, has a response body like this:

   <?xml version='1.0' encoding='UTF-8'?>
   <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
   	xmlns:xsd="http://www.w3.org/2001/XMLSchema"
   	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   	xmlns="http://marketing.ews.yahooapis.com/V3">

      <soap:Header>
      ...
      </soap:Header>

      <soap:Body>
         <getCampaignsResponse>
            <out>
               <Campaign>
                  ...
               </Campaign>

               <Campaign>
                  ...
               </Campaign>
            </out>
         </getCampaignsResponse>
      </soap:Body>
   </soap:Envelope>

Errors and Exceptions

If your SOAP request is successful, the EWS web server will return an HTTP 200 OK response code and the SOAP response as described above.

If an error or exception occurs during the processing of your SOAP request, the EWS web server will return an error code and a message. The body will contain a Fault element, which consists of a faultcode element, a faultstring element, and a detail element:

   <?xml version='1.0' encoding='UTF-8'?>
   <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
        xmlns:xsd="http://www.w3.org/2001/XMLSchema"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xmlns:yns="http://marketing.ews.yahooapis.com/V3">

      <soap:Body>
        <soap:Fault>
          <faultcode>soap:Client</faultcode>
          <faultstring>Quota exceeded</faultstring>
          <detail>
            <yns:ApiFault>
               <yns:code>E1015</yns:code>
               <yns:message>Quota exceeded</yns:message>
            </yns:ApiFault>
          </detail>
        </soap:Fault>
      </soap:Body>
   </soap:Envelope>

See SOAP Faults for a list of EWS fault codes and error messages.

Complete Example

This example shows a complete SOAP response for adding campaigns.

   <?xml version='1.0' encoding='UTF-8'?>
   <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
   	xmlns:xsd="http://www.w3.org/2001/XMLSchema"
   	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   	xmlns="http://marketing.ews.yahooapis.com/V3">

      <soap:Header>
         <remainingQuota>9999974</remainingQuota>
         <commandGroup>Marketing</commandGroup>
         <timeTakenMillis>2813</timeTakenMillis>
      </soap:Header>

      <soap:Body>
         <addCampaignsResponse>
            <out>
             <CampaignResponse>
               <campaign>
                  <ID>5354501</ID>
                  <accountID>9901673</accountID>
                  <advancedMatchON>true</advancedMatchON>
                  <campaignOptimizationON>false</campaignOptimizationON>
                  <contentMatchON>true</contentMatchON>
                  ...
               </campaign>
               <errors xsi:nil="true" />
               <operationSucceeded>true</operationSucceeded>
             </CampaignResponse>

             <CampaignResponse>
               <campaign>
                  <ID>5355001</ID>
                  <accountID>9901673</accountID>
                  <advancedMatchON>true</advancedMatchON>
                  <campaignOptimizationON>false</campaignOptimizationON>
                  <contentMatchON>true</contentMatchON>
                  ...
               </campaign>
               <errors xsi:nil="true" />
               <operationSucceeded>true</operationSucceeded>
             </CampaignResponse>
            </out>
         </addCampaignsResponse>
      </soap:Body>
   </soap:Envelope>

Getting Started Guide: EWS Responses