Common issues that lead to SOAP faults (Part II)

Welcome to part 2 of the series of posts that will give tips and tricks on how to deal with SOAP issues. As a SOAP-based web service, AdWords API can be easy to make calls to. At the same time, it can sometimes be difficult to debug the SOAP faults. In the last episode, we discussed how using an invalid Developer token could lead to SOAP faults. Now, below, we'll talk about dealing with missing headers in your SOAP requests.

No Header

New developers are also likely to get the error "The client request did not contain a [header type] header." (Error code 1, 2, 8...).

• If you get this error, the most obvious reason is that you haven’t mentioned a required SOAP header in your request XML. Each SOAP request requires the following headers: "email", "password", "developerToken", "applicationToken", and "useragent". In addition, you may also need to include the "clientEmail" or "clientCustomerId" header, depending on the API method you’re calling.

• Another possible reason for getting this error is that you have mentioned all the required headers, but have provided the wrong XML namespace in your XML. For example, if you send the following header request to https://adwords.google.com/api/adwords/v12/AccountService, you will get the error that email header was missing.

<soap:Header>

   <email xmlns="https://adwords.google.com/api/adwords/v11">INSERT_YOUR_ EMAIL _HERE</email>

   <!--more nodes-->

</soap:Header>

• The best way to fix this issue is to turn on SOAP XML logging and check your SOAP request XML for missing header values. A well-formed SOAP request message looks something like this:

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
   <soap:Header>

     <applicationToken xmlns="https://adwords.google.com/api/adwords/v12">INSERT_APPLICATION_TOKEN_HERE</applicationToken>

     <developerToken xmlns="https://adwords.google.com/api/adwords/v12">INSERT_DEVELOPER_TOKEN_HERE</developerToken>

     <email xmlns="https://adwords.google.com/api/adwords/v12">INSERT_YOUR_EMAIL_HERE</email>

     <password xmlns="https://adwords.google.com/api/adwords/v12">INSERT_YOUR_PASSWORD_HERE</password>

     <useragent xmlns="https://adwords.google.com/api/adwords/v12">INSERT_YOUR_USERAGENT_HERE</useragent>

   </soap:Header>

   <soap:Body>

     <getAccountInfo xmlns="https://adwords.google.com/api/adwords/v12"/>
   </soap:Body>

</soap:Envelope>

 

If you are using AdWords API code samples, then the headers are mentioned within the source code itself. If you are using an AdWords API client library, then the headers are often mentioned in an appropriate configuration file. The .NET client library uses app.config, the Java and Ruby client libraries use adwords.properties file and APIlity uses authentication.ini to store the header values. The Python library uses auth.pkl. You can inspect these files to see if the required headers are mentioned in the configuration files. Finally, all the client libraries have an appropriate constructor, which can accept the required headers and initialize the library, so you might want to inspect the code that initializes the library as well.

Next time, we'll explore errors related missing API operations and methods.



--Anash Oommen, AdWords API Team

Common issues that lead to SOAP faults (Part I)

As a SOAP-based web service, AdWords API can be easy to make calls to. At the same time, it can sometimes be difficult to debug the SOAP faults. We thought it would be useful to go over the most common SOAP faults that you might encounter while making AdWords API calls. To keep things fresh, we also decided to try a new format -- a series of posts. Hope you like it!

Invalid Developer Token

The most common error, encountered by developers making API calls for the first time, is "The developer token is invalid." (Error code 42). There are couple of main reasons you may get this error.

• If this is your first time making the call, make sure that you’re making calls to the account in production environment (adwords.google.com) rather than the AdWords API sandbox (sandbox.google.com). API sample code is configured by default to send the requests to sandbox account and not production account. Thus, if you started programming using this code, this is the most likely reason for the error.

• Similarly, if you are using an AdWords API client library, they are also configured by default to send request to the AdWords API sandbox. If you are using Java, .NET or Ruby client libraries, make sure that you haven’t provided "alternateUrl" key as part of user credentials in the configuration file (adwords.properties or app.config). For Apility library, make sure that Use_Sandbox key is set as ‘No’ in settings.ini file. For python client library, make sure you haven't provided an argument server="'https://sandbox.google.com'" when initializing service class. Also, each library has an appropriate constructor which will accept the credentials as parameters while initializing the library. Make sure that you haven’t provided “alternateUrl” here as well. Finally, some libraries might provide utility functions (e.g. .NET client library provides useSandbox()) that will allow you to switch between production and sandbox accounts at runtime. Make sure that these functions are not called in your code.

• A less common, but more obvious, reason for this error is that the token in your code is invalid. The chance of this happening is low, since most developers copy their token from their MCC account. Nevertheless, it could happen if you’ve mistakenly swapped the application and developer tokens, or if you’ve reset the developer token in your account but forgotten to update your code. Double checking your code should help you spot the reason for the error.

Next time, we'll explore errors related to missing headers in SOAP requests. Keep an eye on the blog for upcoming posts.

--Anash Oommen, AdWords API Team

AdWords Downtime: September 13, 10am-2pm PDT

We'll be performing routine system maintenance on Saturday, September 13 from approximately 10:00am to 2:00pm PDT. You won't be able to access AdWords or the API during this time frame, but your ads will continue to run as normal.

Cheers,
-Jeffrey Posnick, AdWords API Team

Your software on a diet!

Cutting API calories from your app

One of the questions we often get asked by developers is how to spend fewer API units; if you're not careful, you might end up wasting a lot unnecessarily. Thankfully, you should be able to curb your software's appetite with a few simple suggestions:

- Two ways to get there
Do you run a lot of campaigns across your client accounts? If so, you might want to schedule Campaign Performance reports instead of using the getCampaignStats method of the Campaign Service. Conversely, if you keep few campaigns, the second option is probably better.

- Bird's-eye view
Sometimes you just need to retrieve a big chunk of an account's data, with few details. If you've got a lot of campaigns, ad groups, ads, or keywords, it might be a good idea to schedule a Structure report instead. That will give you a nice list of what you're looking for in a much more scalable approach.

- Schedule once, run forever
If you often need the same report, you might want to consider scheduling a periodic report via the AdWords website. It will automatically get generated every day, every week, or every month, and
all you have to do is retrieve it with the Report Service methods.

- Look before you leap
Whenever you submit a new ad or criterion, you should always validate it first. It's true that the validation method has a cost too, but it's significantly smaller than the cost of failing the submission.

- Can I have the list?
After reading the previous item, you might be thinking that it's a good idea to only submit one item at a time. Actually, you have no benefit in doing so, because in a failed call you only get charged for the items that did in fact fail. You should always submit lists of items, since that's how our system is optimized to work -- give it a bunch of data and it will happily take care of it for you.

- Find the differences
A common mistake when updating items (ads, criteria, etc.) is to include items that haven't actually been changed. This will add to your costs, with no benefit! A simple way of making sure this doesn't happen is to keep two separate lists of items in your software: one before modification, and one after. Before submitting the changes to the service, just compare the two and remove the identical items.

- No one's looking for that
Keywords are what advertising on the search network is all about. If you have the right keywords, people will find you. If you don't, business will be slow. Consider for a moment how many poorly performing keywords you have. Every time you retrieve them, update them, or check their statistics via the API, you spend units. One very good way of saving units in the long run is to make sure that you go for the best, and skip the rest. One of the easiest ways of doing this is to use the Traffic Estimator Service before you add them, in order to get an idea of how much traffic those keywords would generate.

- Go play in the sandbox
Are you still developing your application, or trying out some new functionality? Well, no need to be spending any units. After all, playing should be free! We've got a sandbox ready for you to test your code during development which is free and open to anyone, so you can hack away without worrying about how many times you've tried to get that right.

- Check the price before you buy
Finally, you should keep in mind the cost of the various API methods, so that you don't run into any surprises after running your software. The latest rate sheet is always available at this page.


Have you come across any other useful tricks to keep API usage costs down? If so, share with others!

Cheers,
-Sérgio Gomes, AdWords API Team

AdWords Downtime: August 23, 10am-4pm PDT

We'll be performing routine system maintenance on Saturday, August 23 from approximately 10:00am to 4:00pm PDT (note the 4:00pm PDT end time). You won't be able to access AdWords or the API during this time frame, but your ads will continue to run as normal.

Cheers,
-Jeffrey Posnick, AdWords API Team

Sunsetting V11 on August 26th, 2008

In accordance with our policy of sunsetting older versions of the AdWords API, we will turn off access to version 11 of the API on Tuesday, August 26, 2008. Version 12 of the API has been available for over four months now, and supports a number of new features. We hope that you've already taken the opportunity to upgrade your code.

The latest versions of the publicly available client libraries all support version 12 of the API, so if you're using one of those, please check the relevant README file for information on how to switch from version 11 to 12. The migration process should be fairly straightforward, but one thing in particular to watch out for is that ad group ids are no longer ints; they're now longs in version 12.

As always, if you have any questions about the AdWords API or upgrading to our latest versions, you can check out our Frequently Asked Questions or ask them in our developer forum.

Cheers,
-Jeffrey Posnick, AdWords API Team

AdWords Downtime: August 9, 10am-2pm PDT

We'll be performing routine system maintenance on Saturday, August 9 from approximately 10:00am to 2:00pm PDT. You won't be able to access AdWords or the API during this time frame, but your ads will continue to run as normal.

Cheers,
-Jeffrey Posnick, AdWords API Team