Error types

  • Errors are broadly categorized into Authentication, Retryable, Validation, and Sync-related types to help structure error handling.

  • Authentication errors occur when your app lacks permission to access Google Ads on a user's behalf, often due to revoked access.

  • Retryable errors suggest a temporary issue that may be resolved by retrying the request with an exponential backoff.

  • Validation errors indicate unacceptable input to an operation, requiring user input correction or back-end review.

  • Sync-related errors arise when your local database is out of sync with Google Ads objects, potentially requiring database updates or manual review.

We've categorized errors into the following broad categories:

  • Authentication
  • Errors that can be retried
  • Validation
  • Sync-related

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. See the following resources for more details about specific errors:

  • Common errors provides more details about a particular error.
  • google.rpc.Status provides details about the logical error model used by the API.
  • Canonical error codes provides a list and explanation of canonical error codes defined by gRPC and HTTP in the context of the Google Ads API.

Authentication errors

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

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.

Relatedly, if your Google Cloud project only has the Test access level and attempts to make requests against a production (non-test) account, the API returns an AuthorizationError whose enum value depends on the API version:

Errors that can be retried

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

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 requests initiated on the backend, your app should automatically retry the request up to a maximum number of retries.

When you retry requests, use an exponential backoff policy with randomized jitter. 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, adding a small random delay to each interval to prevent synchronized retry spikes. Exponential backoff helps ensure you are not calling the API too aggressively. If an error persists after exhausting retries, log the request-id from the response for troubleshooting.

Validation errors

Validation errors indicate that an input to an operation was not acceptable. Examples include 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 backend, 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.

For backend 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.

Next
Understand API errors