瞭解 API 錯誤

本指南說明 Google Ads API 如何處理及傳達錯誤。瞭解 API 錯誤的結構和意義，對於建構穩健的應用程式至關重要，因為這類應用程式可妥善處理各種問題，從無效輸入到暫時無法使用服務，都能應付自如。

Google Ads API 遵循標準 Google API 錯誤模型，該模型以 gRPC 狀態碼為基礎。如果 API 回應發生錯誤，就會包含 Status 物件，內含下列資訊：

• 數字錯誤代碼。
• 錯誤訊息。
• 選填，其他錯誤詳細資料。

標準化錯誤代碼

Google Ads API 會使用 gRPC 和 HTTP 定義的一組標準錯誤代碼。這些代碼會大致指出錯誤類型。您應一律先檢查這個數字代碼，瞭解問題的根本性質。

下表摘要說明使用 Google Ads API 時，您可能會遇到的最常見代碼：

如要進一步瞭解這些代碼，請參閱 API 設計指南 - 錯誤代碼。

瞭解錯誤詳細資料

除了頂層代碼之外，Google Ads API 還會在 Status 物件的 details 欄位中提供更具體的錯誤資訊。這個欄位通常包含 GoogleAdsFailure 原型，其中包含個別 GoogleAdsError 物件的清單。

每個 GoogleAdsFailure 物件都包含：

• errors：GoogleAdsError 物件清單，詳細說明發生的各項錯誤。
• request_id：要求的專屬 ID，可用於偵錯和支援。

每個 GoogleAdsError 物件會提供：

• errorCode：更精細的 Google Ads API 專屬錯誤代碼，例如 AuthenticationError.NOT_ADS_USER。
• message：使用者可自然閱讀的特定錯誤說明。
• trigger：導致錯誤的值 (如適用)。
• location：說明要求中發生錯誤的位置，包括欄位路徑。
• details：其他錯誤詳細資料，例如未發布的錯誤原因。

錯誤詳細資料範例

收到錯誤時，用戶端程式庫會允許您存取這些詳細資料。舉例來說，INVALID_ARGUMENT (代碼 3) 可能會有如下的 GoogleAdsFailure 詳細資料：

{
  "code": 3,
  "message": "The request was invalid.",
  "details": [
    {
      "@type": "type.googleapis.com/google.ads.googleads.v17.errors.GoogleAdsFailure",
      "errors": [
        {
          "errorCode": {
            "fieldError": "REQUIRED"
          },
          "message": "The required field was not present.",
          "location": {
            "fieldPathElements": [
              { "fieldName": "operations" },
              { "fieldName": "create" },
              { "fieldName": "name" }
            ]
          }
        },
        {
          "errorCode": {
            "stringLengthError": "TOO_SHORT"
          },
          "message": "The provided string is too short.",
          "trigger": {
            "stringValue": ""
          },
          "location": {
            "fieldPathElements": [
              { "fieldName": "operations" },
              { "fieldName": "create" },
              { "fieldName": "description" }
            ]
          }
        }
      ]
    }
  ]
}

在這個範例中，雖然頂層為 INVALID_ARGUMENT，但 GoogleAdsFailure 詳細資料會說明 name 和 description 欄位造成問題的原因 (分別為 REQUIRED 和 TOO_SHORT)。

找出錯誤詳細資料

存取錯誤詳細資料的方式，取決於您使用的是標準 API 呼叫、部分失敗或串流。

標準和串流 API 呼叫

如果 API 呼叫失敗，且未使用部分失敗 (包括串流呼叫)，系統會傳回 GoogleAdsFailure 物件，做為 gRPC 回應標頭中尾隨中繼資料的一部分。如果您使用 REST 進行標準呼叫，HTTP 回應中會傳回 GoogleAdsFailure。用戶端程式庫通常會將此情況視為例外狀況，並提供 GoogleAdsFailure 屬性。

部分失敗

如果您使用部分失敗，失敗作業的錯誤會傳回至回應的 partial_failure_error 欄位，而非回應標頭。在本例中，GoogleAdsFailure 會嵌入回應中的 google.rpc.Status 物件。

Batch 工作

如要查看批次處理的個別作業錯誤，請在工作完成後擷取批次工作結果。如果作業失敗，每個作業結果都會包含 status 欄位，其中含有錯誤詳細資料。

要求 ID

request-id 是用來識別 API 要求的專屬字串，對於疑難排解至關重要。

您可以在多個位置找到 request-id：

• GoogleAdsFailure：如果 API 呼叫失敗並傳回 GoogleAdsFailure，則會包含 request_id。
• 尾端中繼資料：無論要求成功或失敗，request-id 都會顯示在 gRPC 回應的尾端中繼資料中。
• 回應標頭：無論要求成功或失敗，request-id 也都會出現在 gRPC 和 HTTP 回應標頭中，但成功串流要求除外。
• SearchGoogleAdsStreamResponse：如果是串流要求，每個 SearchGoogleAdsStreamResponse 訊息都包含 request_id 欄位。

記錄錯誤或聯絡支援團隊時，請務必附上 request-id，以利診斷問題。

錯誤處理最佳做法

如要建構具備韌性的應用程式，請實作下列最佳做法：

1. 檢查錯誤詳細資料：請務必剖析 Status 物件的 details 欄位，特別是尋找 GoogleAdsFailure。errorCode、message 和 location GoogleAdsError 提供的詳細資訊最實用，有助於偵錯和收集使用者意見回饋。

2. 區分用戶端和伺服器錯誤：

   • 用戶端錯誤：例如 INVALID_ARGUMENT、NOT_FOUND、PERMISSION_DENIED、FAILED_PRECONDITION、UNAUTHENTICATED 等代碼。這類錯誤需要變更要求，或應用程式的狀態/憑證。請先解決問題，再重試要求。
   • 伺服器錯誤：例如 UNAVAILABLE、INTERNAL、DEADLINE_EXCEEDED、UNKNOWN 等代碼。這表示 API 服務暫時發生問題。

3. 導入重試策略：

   • 何時重試：僅針對暫時性伺服器錯誤重試，例如 UNAVAILABLE、DEADLINE_EXCEEDED、INTERNAL、UNKNOWN 和 ABORTED。
   • 指數輪詢：使用指數輪詢演算法，在每次重試之間等待越來越長的時間。以免服務因壓力過大而超載。舉例來說，先等待 1 秒，再等待 2 秒，然後等待 4 秒，依此類推，直到達到重試次數上限或總等待時間。
   • 時基誤差：在退避延遲中加入少量隨機「時基誤差」，避免「雷鳴群」問題，也就是多個用戶端同時重試。

4. 完整記錄：記錄完整的錯誤回應，包括所有詳細資料，尤其是要求 ID。這項資訊對於偵錯至關重要，如有需要，也能向 Google 支援團隊回報問題。

5. 提供使用者意見回饋：根據具體的 GoogleAdsError 程式碼和訊息，向應用程式使用者提供清楚實用的意見回饋。舉例來說，您可以顯示「廣告活動名稱為必填欄位」或「找不到提供的廣告群組 ID」，而不是只顯示「發生錯誤」。

只要遵循這些規範，就能有效診斷及處理 Google Ads API 傳回的錯誤，進而打造更穩定且易於使用的應用程式。