錯誤類型

我們已將錯誤分為下列廣泛類別:

  • 驗證
  • 可重試
  • 驗證
  • 同步相關

雖然這些類別並未涵蓋所有可能的錯誤,且部分類別可能符合多個類別,但可能無法做為建構應用程式錯誤處理的起點。如要進一步瞭解特定錯誤,請參閱常見錯誤

驗證錯誤

「驗證」是指使用者是否已授予應用程式代表使用者存取 Google Ads 的權限。驗證是由 OAuth2 流程產生的憑證管理。

因超出您控制的因素導致驗證錯誤最常見的原因是,已驗證的使用者撤銷了他們授予應用程式代表他們執行操作的權限。舉例來說,如果您的應用程式為個別客戶管理個別 Google Ads 帳戶,並在管理該客戶帳戶時分別驗證每個用戶端,則用戶端隨時可能撤銷您的應用程式存取權。視您的存取權撤銷時間而定,API 可能會直接傳回 AuthenticationError.OAUTH_TOKEN_REVOKED 錯誤,或者用戶端程式庫中的內建憑證物件可能會擲回憑證遭到撤銷的例外狀況。無論是哪一種情況,如果應用程式有用戶端使用的 UI,都可以要求用戶端重新啟動 OAuth2 流程,重新建立應用程式的權限,以便代表客戶採取行動。

可重試的錯誤

有些錯誤 (例如 TRANSIENT_ERRORINTERNAL_ERROR) 可能表示暫時性問題,可在短暫暫停後重試要求,或許就能解決。

針對使用者提出的要求,其中一項策略是立即在 UI 中指出錯誤,並為使用者提供觸發重試的選項。或者,應用程式可以先自動重試要求,只有在重試次數達到上限或使用者等待時間總時間之後,才在 UI 中顯示錯誤。

針對在後端發出的要求,應用程式應自動重試要求,最多可重試次數上限。

重試要求時,請採用指數輪詢政策。例如,如果您在第一次重試前首次暫停 5 秒,則可在第二秒過後暫停 10 秒,並在第三次重試後暫停 20 秒。指數輪詢有助於確保您不會過度積極呼叫 API。

驗證錯誤

驗證錯誤表示對作業的輸入內容未接受。例如:PolicyViolationErrorDateErrorDateRangeErrorStringLengthErrorUrlFieldError

驗證錯誤最常發生於使用者啟動的要求中,也就是使用者輸入無效的輸入內容。在這種情況下,您應根據收到的特定 API 錯誤,向使用者提供適當的錯誤訊息。您也可以在發出 API 呼叫前,驗證使用者輸入內容是否有常見錯誤,藉此提高應用程式回應效率和 API 使用效率。如果是來自後端的要求,應用程式可以將失敗的作業加入佇列,供真人作業人員審查。

許多 Google Ads 應用程式都有本機資料庫,用來儲存 Google Ads 物件。此方法有一個難題是,本機資料庫可能會與 Google Ads 中的實際物件不同步。舉例來說,使用者可能會直接在 Google Ads 中刪除廣告群組,但應用程式和本機資料庫不受變更影響,導致系統以類似廣告群組的方式繼續發出 API 呼叫。這些同步處理問題可能會以各種錯誤呈現,例如 DUPLICATE_CAMPAIGN_NAMEDUPLICATE_ADGROUP_NAMEAD_NOT_UNDER_ADGROUPCANNOT_OPERATE_ON_REMOVED_ADGROUPAD 等。

針對使用者啟動的要求,其中一個策略是提醒使用者留意可能發生的同步處理問題、立即啟動工作來擷取 Google Ads 物件的相關類別,並更新本機資料庫,然後提示使用者重新整理 UI。

對於後端要求,有些錯誤會提供足夠的資訊,讓應用程式自動及逐步修正本機資料庫。舉例來說,CANNOT_OPERATE_ON_REMOVED_ADGROUPAD 應該會導致您的應用程式標示本機資料庫已移除這則廣告。無法透過這種方式處理的錯誤可能會導致應用程式啟動更完整的同步處理工作,或排入佇列等待真人營運者審查。