4.5 Error Handling

Introduction

---

Throughout this guide, we've mentioned the potential issues that could arise within the Performance Max setup flow. However, issues may also arise outside of the flow, after the merchant has created its Performance Max campaign. Proper error handling is so critical to the success of your integration that this section is dedicated to elaborate more on best practices when it comes to error handling.

This section only covers common issues that:

• Can affect the serving of Performance Max campaigns, excluding errors already mentioned in Step 3 (that are not specific to ads).

• Are severe and can lead to account suspension, product disapproval or the campaign not being able to serve. Issues classified as "warnings" are not listed.

• Require resolution by the merchant. Common issues that should be resolved by you, such as errors with your conversion tracking implementation (recording zero conversions or unnecessary conversions such as page views) are not covered in this section. Refer to the earlier sections, especially the tips to mitigate the risk of hitting these issues post launch.

• Require Requesting Review for Ads. New Merchant Support Method for enabling request review.

Important: Plan to implement these new Merchant Support methods by the end of this year. Forthcoming, the API plans to be expanded to enable requesting re-review or performing other actions directly through the API (your merchants can request the action directly in your UI).

Specifically, this section covers the following 6 issues with Ads account:

1. Limited access to the ads account
2. Two-step verification required
3. Account suspended
4. Advertiser verification
5. Missing payment information (for direct billing scenario)
6. Conversion tracking setup conflict due to existing conversion tracking

For each issue, a brief description, a link to the relevant implementation section in this guide, the merchant resolution steps, and suggestions on where to surface the issue are provided.

UX Guidance

---

For more details on Google Ads account level errors during onboarding see the last bit of the section Ads Account Creation.

After onboarding, Google Ads account level errors should be surfaced app-wide and at the campaign level. An example for how this can look like for the scenario of broken billing information is shown below.

Below is an overview of all Google Ads account-level errors and how they could show up at campaign- and page-level.

Other issues limiting ads from serving should be treated the same way. Below is an example of how a failed product sync could look like.

If multiple Google Ads account level errors exist: In order not to overwhelm the user we recommend only showing the most severe Google Ads account level error at a time and revealing the next most severe once the previous one has been resolved. Google proposes the following hierarchy:

Tech Guidance

---

The Ads API documentation covers best practices around general error handling when making API calls. This section covers more conceptual errors that can impact the success of the merchant's Performance Max campaign.

2-Step Verification required

If you require users to set up 2SV, the error TWO_STEP_VERIFICATION_NOT_ENROLLED is returned if API calls are made using access tokens generated from a refresh token that was issued prior to the user enabling 2-Step Verification. The application should handle this error and direct the user to enable 2-Step Verification for their Google account at:

    https://safety.google/authentication/

See the section 2-Step Verification of this guide for more details.

Account suspended

A Google Ads account can be suspended for several reasons. You can check the status of a Google Ads account using the custome.status to see if the value "SUSPENDED" is returned.

If the account is suspended, you should alert the merchant to this status and direct them to either:

1. Click the in-account notification in the Google Ads Front End to see more information and go through the steps to submit an appeal.

2. Check their emails for a notification email from Google. The email contains the Google Ads account CID that was suspended, the suspension reason, and a link to submit an appeal if the merchant believes the account was suspended in error.

Limited Access to Ads Accounts

To link a Google Ads account to a Merchant Center account, the Google Ads user account must have admin access level.

If a merchant tries to link an existing Google Ads account in which they are a user with Read-only or Standard access, the API call encounters an error. Merchants utilizing your application to link an existing Google Ads account in which they are a user with Read-only or Standard access may encounter an error related to limited Ads access when an API call is made to link the Google Ads account and Merchant Center account.

You should alert the merchant to ask a member of their team with administrator access to the existing Google Ads account to either

1) Upgrade the user account to an administrator account; or

2) Go through the onboarding flow for the application again with the administrator access user account.

Payment information missing (for direct billing scenario)

If the Ads account is missing payment information, the campaigns in that account don't run. You can check if the merchant has completed the billing setup using BillingSetupStatus. Any value other than "APPROVED" causes ads not serving.

As per the implementation steps, you may have given merchants a deep link to the Google Ads UI during onboarding, but they may not have gone ahead and added their payment information (see other payment issues).

You should alert the merchant to this billing issue and resurface the deep link to them for completing the billing setup. Alternatively if the deep link is unavailable, you can direct the merchant to visit the Google Ads Front End

Tools and settings > Billing > Settings to complete setup.

Multiple conversion actions warning

If you allow merchants to reuse an existing Google Ads account, they may already have configured their website.