Error Types

We've categorized errors into the following broad categories:

Authentication

Retryable

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. Refer to
Common Errors for more details about a
particular error.

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.

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

When you retry requests, use an exponential 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.

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.

Sync-related errors

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 back-end 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.