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:Fault> <faultcode>soap:Server</faultcode> <faultstring> [EntityNotFound.INVALID_ID @ operations.operand.campaignId; trigger:'CampaignId: 123'] </faultstring> <detail> <ApiExceptionFault xmlns="https://adwords.google.com/api/adwords/cm/v201802"> <message> [EntityNotFound.INVALID_ID @ operations.operand.campaignId; trigger:'CampaignId: 123'] </message> <ApplicationException.Type>ApiException</ApplicationException.Type> <errors xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="EntityNotFound"> <fieldPath>operations.operand.campaignId</fieldPath> <fieldPathElements> <field>operations</field> <index>0</index> </fieldPathElements> <fieldPathElements> <field>operand</field> </fieldPathElements> <fieldPathElements> <field>campaignId</field> </fieldPathElements> <trigger>CampaignId: 123</trigger> <errorString>EntityNotFound.INVALID_ID</errorString> <ApiError.Type>EntityNotFound</ApiError.Type> <reason>INVALID_ID</reason> </errors> </ApiExceptionFault> </detail> </soap:Fault>
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--see your library's README for details.
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.
Blog posts will on occasion be a good reference when troubleshooting your application. Likewise, the AdWords Help Center will help when troubleshooting validation or account limit issues--the AdWords API inherits the rules and limitations of the core AdWords 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 occurred.
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 troubleshooting.
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.