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