When writing software to access the AdWords API, you will at some point run into
an error message. This could be caused by a bug in your software or by invalid
input from a user. No matter the source, you will need to troubleshoot the error
and either fix your code or add logic to handle the user error. This guide
discusses some best practices when troubleshooting errors from the AdWords API.
First Step: Determine what exactly the problem is
Your first troubleshooting step is to gather more information about the issue.
The AdWords API generally reports error messages as
(unless the XML itself does not validate against the WSDL). These faults contain
faultstring as well as detail elaborating on why the fault occurred. These
faults are your first indication of what the problem is.
soap:Server [EntityNotFound.INVALID_ID @ operations.operand.campaignId; trigger:'CampaignId: 123'] [EntityNotFound.INVALID_ID @ operations.operand.campaignId; trigger:'CampaignId: 123'] ApiException operations.operand.campaignId operations 0 operand campaignId CampaignId: 123 EntityNotFound.INVALID_ID EntityNotFound INVALID_ID
Most of our client libraries throw an
exception encapsulating the SOAP fault. Most SOAP toolkits behave similarly.
These exceptions usually end up in application logs for later perusal. Looking
at these logs is a great way to start troubleshooting. Many larger applications
(especially those using third party libraries) may also log additional
information that will help you later when trying to fix this problem. Our client
libraries support logging SOAP requests. Refer to our library’s README for
Once you know what happened, you’ll need to figure out what the error means.
Second Step: Research the error
Your first stop for researching errors should always be our
Common Errors documentation. This
doc covers a large proportion of errors that are commonly experienced by our
developers. It describes the error message, relevant API references and how to
avoid or handle the error.
If our common errors documentation doesn’t specifically mention the error,
you should consult our reference documentation
and look for the error string.
If you still need more information after reading the Common Errors page and
our documentation, we have several other great resources. Our
forums are frequented
by many AdWords API developers sharing their experiences with the API. Searching
them is always a good step when trying to troubleshoot a problem with your
application; chances are someone else has run into it! If you run across any
errors that are not documented, please bring this to our attention on the forum.
As a last resort, you can try an Internet search on the error message.
will on occasion be a good reference when troubleshooting your application.
Likewise, the Google Ads Help Center will
help when troubleshooting validation or account limit issues; the AdWords API
inherits the rules and limitations of the core Google Ads product.
Once you know more about the error, it’s time to find the root cause.
Third Step: Figuring out what is the cause of the error message
Back to the logs to determine the cause of the error. Many libraries will log
useful information at debug or info levels. Our client libraries give you the
choice to log the actual SOAP messages sent and received. After looking at the
SOAP response, check the SOAP request for a possible cause. Some API error
message will also include a fieldPath indicating where in the request the error
When troubleshooting an issue, it may be that your application is providing the
wrong information to the API. We strongly encourage the use of an Interactive
Development Environment (IDE) such as Eclipse (a free
and open source IDE which is primarily used to develop Java, but has plugins for
other languages) to aid you in debugging. It will allow you to set breakpoints
and step through your code line by line.
Double check to make sure the SOAP request matches your application inputs
(e.g. maybe the Campaign’s name isn’t making it to the request). You could also
try to add or remove fields from the request–the AdWords API supports
Omitting a field indicates the API should leave it alone. If your application
retrieves an object, makes a change and sends it back, it’s possible you may be
writing to a field that does not support updating. Check our
reference documentation–fields marked
ReadOnly should not be sent in a request.
How to get help
It’s not always possible to identify and solve the problem all on your own.
Asking on the forum will get
your question seen by thousands of developers who may have seen the same issue
and have advice for you.
Please try to include as much information as possible when seeking help.
Recommended items include:
- Sanitized SOAP XML request and response. Make sure to remove sensitive
information such as your developer token or AuthToken. Showing the structure of
your request/response is useful for anyone troubleshooting.
- Code snippets. If you are having a language-specific problem or are
requesting help working with the API, including a snippet of code can help
explain what you are doing.
- RequestId – this piece of information will help
Google Developer Relations team members locate your request if made in the
last 8 days against the production environment. We recommend including the
SOAP XML logs if possible as they contain the
requestIdas well as more
context than requestId alone. Additional information, such as
runtime/interpreter version and platform can also be useful when
Fourth Step: Fixing the problem
Now that you’ve figured out the problem and come up with a solution, it’s time
to make your change and test the fix against a test account (preferred) or
production (if the bug only applies to data in a specific production account).
Now that you’ve solved this problem, did you notice any ways to improve your
code to avoid this in the first place? We write unit tests for our own client
libraries and recommend you do the same. An ounce of prevention is worth a
pound of cure–writing tests will help you find and fix bugs more quickly than
waiting for a bug report.