錯誤類型

我們將錯誤歸類為下列幾種：

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

雖然這些類別並未涵蓋所有可能的錯誤，且有些錯誤可能適用於多個類別，但仍可做為建構應用程式錯誤處理機制的起點。如要進一步瞭解特定錯誤，請參閱下列資源：

  • 「常見錯誤」提供特定錯誤的詳細資訊。
  • google.rpc.Status，瞭解 API 使用的邏輯錯誤模型詳細資料。
  • 標準錯誤代碼：列出並說明 Google Ads API 環境中，由 gRPC 和 HTTP 定義的標準錯誤代碼。

驗證錯誤

驗證是指使用者是否已授權應用程式代表他們存取 Google Ads。驗證作業是透過 OAuth2 流程產生的憑證進行管理。

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

可重試的錯誤

部分錯誤 (例如 TRANSIENT_ERROR 或 INTERNAL_ERROR) 可能表示暫時性問題，稍後重試要求即可解決。

如果是使用者發出的要求，其中一個策略是在 UI 中立即指出錯誤，並提供重試選項。或者，應用程式可以先自動重試要求，達到重試次數上限或使用者等待時間總計後，再於 UI 中顯示錯誤。

如果是從後端發出的要求，應用程式應自動重試要求，次數上限為最大重試次數。

重試要求時，請使用指數輪詢政策。舉例來說，如果第一次重試前暫停 5 秒，第二次重試前可以暫停 10 秒，第三次重試前暫停 20 秒。指數輪詢可確保您不會過於頻繁地呼叫 API。

驗證錯誤

驗證錯誤表示作業的輸入內容不符規定。 例如 PolicyViolationError、DateError、DateRangeError、StringLengthError 和 UrlFieldError。

驗證錯誤最常發生在使用者發起的請求中，因為使用者輸入的內容無效。在這些情況下，您應根據收到的特定 API 錯誤，向使用者提供適當的錯誤訊息。您也可以在呼叫 API 前，驗證使用者輸入內容是否含有常見錯誤，讓應用程式的回應速度更快，API 使用效率更高。如果是後端提出的要求，應用程式可以將失敗的作業加入佇列，供人工審查。

許多 Google Ads 應用程式會維護本機資料庫，以儲存 Google Ads 物件。這種做法的一項挑戰是，本機資料庫可能會與 Google Ads 中的實際物件失去同步。舉例來說，使用者可能會直接在 Google Ads 中刪除廣告群組，但應用程式和本機資料庫並不知道這項變更，因此會繼續發出 API 呼叫，彷彿廣告群組仍然存在。這些同步問題可能會導致各種錯誤，例如 DUPLICATE_CAMPAIGN_NAME、DUPLICATE_ADGROUP_NAME、AD_NOT_UNDER_ADGROUP、CANNOT_OPERATE_ON_REMOVED_ADGROUPAD 等。

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

如果是後端要求，部分錯誤會提供足夠的資訊，讓應用程式自動且逐步修正本機資料庫。舉例來說，CANNOT_OPERATE_ON_REMOVED_ADGROUPAD 應會導致應用程式在本地資料庫中將該廣告標示為已移除。如果無法以這種方式處理錯誤，應用程式可能會啟動更完整的同步作業，或加入佇列，由人工審查員審查。

下一頁
瞭解 API 錯誤