錯誤類型

我們將錯誤分成以下幾個類別:

  • 驗證機制
  • 可重試
  • 驗證
  • 同步處理相關

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

驗證錯誤

驗證是指使用者是否已授權您的應用程式代為存取 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 應可讓應用程式在本機資料庫中將該廣告標示為已移除。無法以這種方式處理的錯誤,可能會導致應用程式啟動更完整的同步處理工作,或排入佇列供真人作業人員查看。