Best Practices

This guide covers some best practices you can implement to optimize the efficiency and performance of your AdWords API applications.

Ongoing maintenance

To ensure that your app runs uninterrupted:

  • Keep your developer contact email in the AdWords API Center up-to-date. This is the alias we use to contact you. If we're unable to contact you regarding compliance with the API Terms and Conditions, your API access may be revoked without your prior knowledge. Avoid using a personal email address tied to an individual or an unmonitored account.

  • To be informed of issues, such as product changes, maintenance downtime, deprecation dates, and so on, subscribe to our

The forum is regularly monitored by the AdWords API team, making it the ideal place to post API questions.

  • Keep your app compliant with the AdWords API Terms and Conditions (T&C) and Required Minimum Functionality (RMF). If required, the token review and compliance team will reach out to you via your contact email. If you have questions or concerns about the T&C or RMF, you can reach out to the review team by responding to the email they sent you when reviewing your developer token application.


Batch operations

Making a request to the API entails a number of fixed costs, such as round-trip network latency, serialization and deserialization processing, and calls to backend systems. To lessen the impact of these fixed costs and increase overall performance, most mutate() methods in the API are designed to accept an array of operations. By batching multiple operations into each request, you can reduce the number of requests you make and the associated fixed costs. If possible, avoid making requests with only one operation.

For example, suppose you're adding 50,000 keywords to a campaign across multiple ad groups. Instead of making 50,000 requests with 1 keyword each, make 100 requests with 500 keywords each, or even 10 requests with 5,000 keywords each. Note that there are limits on the number of operations allowed in a request, so you may need to adjust your batch size to achieve optimal performance.

An additional benefit of making fewer, larger requests is that your app is less likely to encounter a request-based rate limit.

Group operations

Operations that all target the same ad group or campaign will process faster than the same number of operations targeting many different ad groups or campaigns. Grouping together operations that target the same ad group or campaign reduces the total number of ad groups or campaigns targeted in the request, improving overall performance.

Concurrent requests to the same ad group or campaign may generate a CONCURRENT_MODIFICATION error. Grouping operations that modify the same ad group or campaign in a single request decreases the chance of such a conflict.

Take the example above of adding 50,000 keywords to a campaign across multiple ad groups. Before breaking the operations into batches, a simple approach is to sort the keywords by the ad group they target. This increases the chance that all of the keywords for the same ad group will fall within the same request. It also decreases the total number of ad groups targeted in a single request. More advanced approaches can be applied to ensure that related operations are grouped into as few requests as possible while still maintaining large batches.

Reuse access tokens

Reusing the same OAuth2 access token across threads and processes reduces the overhead of periodically refreshing tokens, and reduces the likelihood that your app will be rate limited due to excessive token refreshes. Learn more about optimizing OAuth2 requests.

Send sparse objects

When objects are sent to the API, fields must be deserialized, validated, and stored in the database. Passing in full objects when you only want to update a few fields can result in extra processing time and decreased performance. To mitigate this, the AdWords API supports sparse updates, allowing you to populate only the fields in an object that you wish to change or that are required. Fields that are unpopulated or have null values are left unchanged, increasing the performance of your requests.

For example, an app that updates keyword-level bids can benefit from using sparse updates, as only the adGroupID, criterionID, and bids fields would need to be populated. In a test using 150 keywords, a 20% performance increase was seen using sparse updates instead of passing fully populated objects.

Use compression

The AdWords API supports gzip compression on SOAP messages in both requests and responses. To enable gzip compression in a response, include these two HTTP headers in your request:

  • User-Agent: containing the string "gzip"
  • Accept-Encoding: with the value gzip


User-Agent: My App (gzip)
Accept-Encoding: gzip

If you're using a client library, see its documentation on enabling compression.

Error handling and management

During development, you're likely to encounter errors. This section describes considerations and strategies when building error management into your app.

In addition to this section, see the troubleshooting guide for more information on managing errors.

Distinguish request sources

Some apps are primarily interactive, issuing API calls directly in response to user-initiated actions in a UI. Others work primarily offline, issuing API calls as part of a periodic backend process. Many apps combine the two. When thinking about error management, it can be useful to distinguish these different types of requests.

For user-initiated requests, your primary concern should be providing a good experience for your users. Use the specific error that occurred to provide the user with as much context as possible in the UI. Where possible, offer easy steps they can take to resolve the error (see suggestions below).

For backend-initiated requests, implement handlers for the different types of errors your app may encounter (see suggestions below). Always include a default handler to address rare or previously unseen errors. A good approach for a default handler is to add the failed operation and error to a queue for a human operator to review and determine an appropriate resolution.

Distinguish error types

Below are four broad categories of errors, each of which should be handled differently. Though these categories don't encompass all possible errors, and some may fit into more than one category, they can nevertheless serve as a starting point for structuring your app's error handling. Refer to Common Errors for more details about a particular error.

  1. Authentication and authorization errors

    • Authentication refers to whether your app has been given permission by a user to access AdWords acting on their behalf. Authentication is managed through credentials generated by the OAuth2 flow.

    • Authorization refers to whether your app, authenticated and acting as a user, is allowed to work with the particular AdWords data it is trying to read or write.

    The most common reason an authentication error arises from factors beyond your control is when the authenticated user revokes the permission they gave your app to act on their behalf. For example, if your app manages separate AdWords accounts for independent clients and authenticates separately as each client when managing that client's account, a client could revoke your app's access at any time. Depending on when your access was revoked, the API may directly return an AuthenticationError.OAUTH_TOKEN_REVOKED error, or the built-in credential objects in the client libraries may throw a token revoked exception. In either case, if your app has a UI for your clients, it could ask them to relaunch the OAuth2 flow to reestablish your app's permission to act on their behalf.

    Another common reason an authorization error arises from factors beyond your control is due to changes in your manager account hierarchy. Apps working with a single manager account hierarchy usually authenticate as an administrator user of their top-level manager account, since this user has the authority to access all of the sub-accounts in the hierarchy. If a user of a sub-account removes the manager link, your app will receive an AuthorizationError.USER_PERMISSION_DENIED error when attempting to access that account. You can use ManagedCustomerService to check whether the sub-account has indeed been removed from the hierarchy.

    Another reason an authorization error can arise is when the user your app authenticated as has their access rights changed. For example, suppose another user with administrator rights on the AdWords account changes your app's authenticated user's rights to read-only. In this case, all mutate requests will fail with an AuthorizationError.USER_HAS_READONLY_PERMISSION error.

    For either example, your app could provide directions for the user, or escalate the issue to an account manager for resolution.

  2. Retryable errors

    Some errors can indicate a temporary problem that may be resolved by retrying the request after a short pause. These include CONCURRENT_MODIFICATION, UNEXPECTED_INTERNAL_API_ERROR, and RATE_EXCEEDED.

    For user-initiated requests, one strategy is to immediately indicate an error in your UI and give the user an option to trigger a retry. Alternatively, your app could first automatically retry the request, only exposing the error in the UI after reaching a maximum number of retries or total user wait time.

    For backend-initiated requests, your app should automatically retry the request up to a maximum number of retries.

    When you retry requests, use an expontential backoff policy. For example, if you first pause 5 seconds before the first retry, you could pause 10 seconds after the second and 20 seconds after the third retry. Exponential backoff helps ensure you are not calling the API too aggressively.

    For RATE_EXCEEDED errors, the amount of time your app pauses before attempting to retry should be at least longer than the retryAfterSeconds field in the error. See the Rate Limits guide for more details. Other retryable errors can be retried sooner but should still follow an exponential backoff policy.

  3. Validation errors

    Validation errors indicate that an input to an operation was not acceptable. Some examples include PolicyViolationError, DateError, DateRangeError, StringLengthError, UrlError, and many others.

    Validation errors occur most commonly in user-initiated requests, where a user has entered invalid input. In these cases, you should provide an appropriate error message to the user based on the specific API error you received. You can also validate user input for common mistakes before making an API call, making your app more responsive and your API usage more efficient.

    For backend-initiated requests, your app could add the failed operation to a queue for a human operator to review.

  4. Sync-related errors

    Many AdWords apps maintain a local database to store their AdWords objects. One challenge to this approach is that the local database may go out of sync with the actual objects in AdWords. For example, a user might delete an ad group directly in AdWords, but the app and local database are unaware of the change and will issue API calls as if the ad group existed. These sync issues can manifest as a variety of errors such as INVALID_ID, DUPLICATE_CAMPAIGN_NAME, DUPLICATE_ADGROUP_NAME, AD_NOT_UNDER_ADGROUP, CANNOT_OPERATE_ON_REMOVED_ADGROUPAD, and many others.

    For user-initiated requests, one possible strategy is to alert the user to a possible sync problem, immediately launch a job that retrieves the relevant class of AdWords objects and updates the local database, then prompt the user to refresh the UI.

    For backend-initiated requests, some errors provide enough information for your app to automatically and incrementally correct your local database. For example, CANNOT_OPERATE_ON_REMOVED_ADGROUPAD should cause your app to mark that ad as removed in your local database. Errors that you cannot handle in this way could cause your app to launch a more complete sync job or be added to a queue for a human operator to review.

Handle partial failures

By default, requests to the API are atomic: If an error occurs during just one operation in the request, all of the operations are aborted. Atomicity is a safe default, but in many cases is undesirable, as the operations might be independent and only the failed ones need to be reviewed. There are two strategies to address this default behavior.

The first strategy is to review the errors in the response, correlate them with the operation(s) that threw the errors, and issue a new request with only the operations that did not throw errors. These operations should now succeed. You could also pass the operations that threw errors to your error handling mechanism (see above) or queue them for review by a human operator.

The second strategy is to enable the partial failure flag in your API requests. When you enable this flag, each operation is treated independently, and an error in one will not prevent the others from being committed. Errors in specific operations are still returned normally. All of our client libraries support this flag.

The primary benefits of using the partial failure flag are simplicity and fewer API calls, as valid operations are committed automatically without you needing to retry them. For most apps, partial failure is appropriate.

However, in some apps it's more useful to have greater control over error handling. For example, suppose an app does not want policy errors in one ad to prevent other ads from being committed, but it does want other errors (such as those that signal a more significant issue) to abort the entire request. To implement this idea, the app should employ the first strategy above.

In either case, note that certain errors can reflect a dependence between operations either one of which would have been valid on its own. Examples include AdGroupAdError.ENTITY_REFERENCED_IN_MULTIPLE_OPS and AdParamError.AD_PARAM_CANNOT_BE_SPECIFIED_MULTIPLE_TIMES.

Sync backends

If your app's users have manual access to AdWords accounts, they may make changes that your app is not aware of, causing your app's local database to go out of sync. As noted above, you can address sync-related errors reactively when they occur, but you can also seek to prevent them proactively. One proactive strategy is to run a nightly sync job on all your accounts, retrieving the AdWords objects in your accounts and comparing against your local database. To make the retrieval efficient, consider using structure reports rather than the regular API services.

Log errors

All errors should be logged to facilitate debugging and monitoring. At a minimum, log the request ID, the operations that caused the error, and the error itself. Other information to log includes customer ID, API service, round-trip request latency, number of retries, and the raw SOAP request and response.

The client libraries provide built-in SOAP logging capabilities as well as the ability to retrieve the requestId header.

Be sure to monitor trends in API errors so that you can detect and address problems with your app. Consider building your own solution or employing one of many available commercial tools that can use your logs to produce interactive dashboards and send automated alerts.


Use test accounts

Test accounts are AdWords accounts that do not actually serve ads. You can use a test account to experiment with the AdWords API and test that your app's connectivity, campaign management logic, or other processing are working as expected. Your developer token does not need to be approved to use it on a test account, so you can start developing with the AdWords API immediately after requesting a developer token, even before your app is reviewed.

Batch targeting ideas

When generating targeting ideas using TargetingIdeaService, the TargetingIdeaSelector accepts a RequestType of either IDEAS or STATS. STATS requests can be used to retrieve statistics of known keywords. To retrieve statistics for multiple keywords, combine them in a single request by listing the keywords in the RelatedToQuerySearchParameter. One TargetingIdea will be returned for each keyword. This is more efficient than making a separate request for each keyword.

Send feedback about...

AdWords API
AdWords API
Need help? Visit our support page.