瞭解 API 錯誤

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

Google Ads API 遵循標準 Google API 錯誤模型，該模型以 gRPC 狀態碼為基礎。每個導致錯誤的 API 回應都包含 Status 物件，其中含有：

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

標準錯誤代碼

Google Ads API 使用一組由 gRPC 和 HTTP 定義的標準錯誤代碼。這些代碼可大致指出錯誤類型。請務必先查看這個數字代碼，瞭解問題的根本性質。

下表列出使用 Google Ads API 時，最常遇到的代碼：

gRPC 代碼	HTTP 代碼	列舉名稱	說明	指引
0	200	OK	沒有錯誤，表示成功。	不適用
1	499	CANCELLED	作業已取消 (通常由用戶端取消)。	通常表示用戶端停止等待。檢查用戶端逾時。
2	500	UNKNOWN	發生不明錯誤，錯誤訊息或詳細資料中可能會有更多資訊。	視為伺服器錯誤。通常可以透過輪詢重試。
3	400	INVALID_ARGUMENT	用戶端指定了無效的引數。這表示發生問題，導致 API 無法處理要求，例如資源名稱格式錯誤或值無效。	用戶端錯誤：請檢查要求參數，確保符合 API 規定。錯誤詳細資料通常會說明哪個引數無效，以及無效的原因，請根據這些詳細資料修正要求。請先修正要求，再重試。
4	504	DEADLINE_EXCEEDED	在作業完成前已過期。	伺服器錯誤：通常是暫時性錯誤。建議您以指數輪詢方式重試。
5	404	NOT_FOUND	找不到某些要求的實體，例如廣告活動或廣告群組。	用戶端錯誤：請確認您嘗試存取的資源是否存在，以及 ID 是否正確。請勿在未修正的情況下重試。
6	409	ALREADY_EXISTS	用戶端嘗試建立的實體已存在。	用戶端錯誤：請避免建立重複的資源。請先確認資源是否存在，再嘗試建立。
7	403	PERMISSION_DENIED	呼叫者沒有執行指定作業的權限。	用戶端錯誤：請檢查 Google Ads 帳戶的驗證、授權和使用者角色。請先解決權限問題，再重試。
8	429	RESOURCE_EXHAUSTED	資源已用盡 (例如超過配額)，或系統超載。	用戶端/伺服器錯誤：通常需要等待。實作指數輪詢，並視情況降低要求比率。請參閱「API 限制和配額」。
9	400	FAILED_PRECONDITION	作業已遭拒絕，因為系統不在執行作業所需的狀態下。例如缺少必填欄位。	用戶端錯誤：要求有效，但狀態有誤。查看錯誤詳細資料，瞭解前置條件失敗的原因。請勿在未修正狀態的情況下重試。
10	409	ABORTED	作業已取消，通常是交易衝突等並行問題所造成。	伺服器錯誤：通常可以安全重試，但請稍候片刻。
11	400	OUT_OF_RANGE	嘗試執行的作業超出有效範圍。	用戶端錯誤：請更正範圍或索引。
12	501	UNIMPLEMENTED	API 未實作或不支援這項作業。	用戶端錯誤：請檢查 API 版本和可用功能。請勿重試。
13	500	INTERNAL	發生內部錯誤，這是伺服器端問題的通用錯誤訊息。	伺服器錯誤：通常可以透過指數輪詢重試。如果問題持續發生，請回報問題。
14	503	UNAVAILABLE	服務暫時無法使用，這極有可能是暫時情況。	伺服器錯誤：強烈建議以指數輪詢方式重試。
15	500	DATA_LOSS	無法復原的資料遺失或損毀。	伺服器錯誤：罕見。表示有嚴重問題。請勿重試。如果問題持續發生，請回報問題。
16	401	UNAUTHENTICATED	要求不含有效的驗證憑證。	用戶端錯誤：請驗證驗證權杖和憑證。請先修正驗證問題，再重試。

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

瞭解錯誤詳細資料

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

每個 GoogleAdsFailure 物件都包含：

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

每個 GoogleAdsError 物件都提供：

• error_code：更精細的 Google Ads API 專屬ErrorCode (常見錯誤)，例如 AuthenticationError.NOT_ADS_USER。
• message：特定錯誤的人類可讀說明。
• trigger：導致錯誤的 Value (如適用)。
• location：ErrorLocation，說明要求中發生錯誤的位置，包括欄位路徑。
• details：其他 ErrorDetails，例如未發布的錯誤原因。

錯誤詳細資料範例

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

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

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

找出錯誤詳細資料

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

標準和串流 API 呼叫

如果 API 呼叫失敗，且未使用部分失敗 (包括串流呼叫)，系統會將 GoogleAdsFailure 物件做為 gRPC 回應標頭中結尾中繼資料的一部分傳回。如果您使用 REST 進行標準呼叫，系統會在 HTTP 回應中傳回 GoogleAdsFailure。用戶端程式庫通常會將這類錯誤顯示為具有 GoogleAdsFailure 屬性的例外狀況。

部分失敗

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

批次工作

如果是批次處理，您可以在工作完成後呼叫 BatchJobService.ListBatchJobResults，找出個別作業的錯誤。如果作業失敗，每個作業結果都會包含 status 欄位，其中含有錯誤詳細資料。

要求 ID

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

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

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

記錄錯誤或聯絡支援團隊時，請務必提供 request-id，協助診斷問題。

錯誤處理的最佳做法

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

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

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 傳回的錯誤，打造更穩定、更易於使用的應用程式。