瞭解 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`	作業已遭拒絕，因為系統不在執行作業所需的狀態下。例如缺少必填欄位。	用戶端錯誤：要求有效，但 state 錯誤。查看錯誤詳細資料，瞭解前提條件失敗的原因。請先更正州/省，再重試。
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 原型，其中包含個別 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，以利診斷問題。

錯誤處理最佳做法

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

檢查錯誤詳細資料：請務必剖析 Status 物件的 details 欄位，特別是尋找 GoogleAdsFailure。詳盡 errorCode、message 和 location GoogleAdsError 提供最實用的資訊，有助於偵錯和收集使用者意見回饋。
區分用戶端和伺服器錯誤：
- 用戶端錯誤：例如 INVALID_ARGUMENT、NOT_FOUND、PERMISSION_DENIED、FAILED_PRECONDITION、UNAUTHENTICATED 等代碼。這類錯誤需要變更要求，或應用程式的狀態/憑證。請先解決問題，再重試要求。
- 伺服器錯誤：例如 UNAVAILABLE、INTERNAL、DEADLINE_EXCEEDED、UNKNOWN 等代碼。這表示 API 服務暫時發生問題。
導入重試策略：
- 何時重試：僅針對暫時性伺服器錯誤重試，例如 UNAVAILABLE、DEADLINE_EXCEEDED、INTERNAL、UNKNOWN 和 ABORTED。
- 指數輪詢：使用指數輪詢演算法，在每次重試之間等待越來越長的時間。以免服務因壓力過大而超載。舉例來說，先等待 1 秒，再等待 2 秒，然後等待 4 秒，依此類推，直到達到重試次數上限或總等待時間。
- 時基誤差：在退避延遲中加入少量隨機「時基誤差」，避免「雷鳴群」問題，也就是多個用戶端同時重試。
完整記錄：記錄完整的錯誤回應，包括所有詳細資料，尤其是要求 ID。這項資訊對於偵錯至關重要，如有需要，也能向 Google 支援團隊回報問題。
提供使用者意見回饋：根據特定 GoogleAdsError 程式碼和訊息，向應用程式使用者提供清楚實用的意見回饋。舉例來說，您可以顯示「廣告活動名稱為必填欄位」或「找不到提供的廣告群組 ID」，而不是只顯示「發生錯誤」。

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

瞭解 API 錯誤 透過集合功能整理內容 你可以依據偏好儲存及分類內容。