

Error Types

We've categorized errors into the following broad categories:

  • Authentication
  • Retryable
  • Validation
  • Sync-related


Authentication errors


The most common reason an authentication error arises from factors beyond your control is that the authenticated user has revoked the permission they gave your app to act on their behalf. For example, if your app manages separate Google Ads 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.

Retryable errors

Some errors, such as INTERNAL_ERROR, can indicate a temporary problem that may be resolved by retrying the request after a short pause.


For requests initiated on the back end, your app should automatically retry the request up to a maximum number of retries.


Validation errors

Validation errors indicate that an input to an operation was not acceptable. For example, PolicyViolationError, DateError, DateRangeError, StringLengthError, and UrlFieldError.

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 requests from the back end, your app could add the failed operation to a queue for a human operator to review.

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

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