常見錯誤

本頁面列出常見錯誤，並提供避免及處理錯誤的訣竅。如需完整的錯誤清單，請參閱錯誤參考資料、瞭解 API 錯誤指南或錯誤類型指南。如需進一步協助，請與 Google Ads API 支援團隊聯絡。

google.rpc.ErrorInfo
ACCESS_TOKEN_SCOPE_INSUFFICIENT	摘要 OAuth 2.0 存取權杖沒有必要範圍。 常見原因 提供的存取權杖不含 Google Ads API OAuth 2.0 範圍，因此要求遭拒。 如何處理 請確認存取權杖具有必要範圍。這項錯誤的常見原因，是您重複使用以另一組 OAuth 範圍產生的現有存取權杖。如要瞭解如何使用必要範圍產生新的存取權杖，請參閱 OAuth 授權參數。 預防秘訣 確認存取權杖具有必要範圍。請使用必要範圍重新驗證使用者，取得具備必要範圍的存取權。如果應用程式使用多個 OAuth 範圍，您可能需要實作精細 OAuth 權限。

google.auth.exceptions.RefreshError
invalid_grant	摘要 權杖已過期或撤銷。 常見原因 如果 Google Cloud Platform 專案的 OAuth 同意畫面設定為外部使用者類型，且發布狀態為「Testing」，則系統核發的更新權杖會在 7 天後到期。 如何處理 Google 專案的發布狀態為「Testing」，因此每 7 天更新權杖就會過期，並收到「invalid_grant」錯誤。前往 Google API 控制台，然後前往「OAuth 同意畫面」。然後將發布狀態變更為 In production，避免更新權杖在 7 天內過期。 預防秘訣 請參閱「未經驗證的應用程式」。

AdError
CANNOT_USE_AD_SUBCLASS_FOR_OPERATOR	摘要 這個運算子無法與 Ad 的子類別搭配使用。 常見原因 嘗試修改廣告的 status 以外的屬性。 如何處理 不適用 預防秘訣 廣告建立後即無法修改。如要修改廣告，請建立新廣告，然後移除舊廣告。不過，您可以使用 MutateAdGroupAds 修改廣告的 status。
INVALID_INPUT	摘要 廣告中的某個欄位含有無效字元。 常見原因 在網址中使用特殊字元。 如何處理 不適用 預防秘訣 在發出 API 要求前，請先驗證應用程式中的網址。
LINE_TOO_WIDE	摘要 廣告中的某個欄位超過長度上限。請參閱「文字廣告簡介」一文。 常見原因 文字行過長。 如何處理 不適用 預防秘訣 請先驗證行長度，再提出 API 要求。

AdGroupAdError
AD_GROUP_AD_LABEL_ALREADY_EXISTS	摘要 這個標籤已與部分廣告相關聯。 常見原因 嘗試將標籤與已建立關聯的廣告建立關聯。 如何處理 不適用 預防秘訣 請先確認要新增的標籤是否已與廣告建立關聯。
CANNOT_OPERATE_ON_REMOVED_ADGROUPAD	摘要 作業嘗試更新已移除的廣告。 常見原因 廣告一經移除就無法再更新，包括變更狀態。 如何處理 不適用 預防秘訣 請確認程式碼不會嘗試更新已移除的廣告。

AdGroupCriterionError
INVALID_KEYWORD_TEXT	摘要 關鍵字文字含有無效字元。請參閱「新增關鍵字」。 常見原因 關鍵字文字包含無效字元。 如何處理 不適用 預防秘訣 向 API 發出要求前，請先驗證應用程式中的關鍵字文字。

AdGroupError
DUPLICATE_ADGROUP_NAME	摘要 正在新增或重新命名廣告群組，但已有其他廣告群組使用該名稱。 常見原因 建立新廣告群組時，使用現有有效或已暫停廣告群組的名稱。 如何處理 記錄錯誤並向使用者顯示錯誤訊息，建議不重複的廣告群組名稱，或顯示使用中的名稱清單。 預防秘訣 不適用

AssetError
DUPLICATE_ASSET	摘要 單一要求中的兩項作業包含資產的建立作業，且兩項作業的二進位資料相同。 常見原因 變更要求含有重複的建立作業，且包含相同的二進位資料。 如何處理 在個別要求中建立素材資源，然後在後續要求中連結至該素材資源；或在同一要求中使用臨時 ID。 預防秘訣 不適用

AuthenticationError
CLIENT_CUSTOMER_ID_INVALID	摘要 客戶顧客 ID 不是數字。 常見原因 使用不當的客戶 ID。 如何處理 不適用 預防秘訣 123-456-7890 應為 1234567890。詳情請參閱「開始使用」一文。
CLIENT_CUSTOMER_ID_IS_REQUIRED	摘要 HTTP 標頭中未指定客戶客戶 ID。 常見原因 未在 HTTP 標頭中指定客戶 ID。 如何處理 不適用 預防秘訣 所有呼叫都必須提供客戶 ID，因此請務必在 HTTP 標頭中指定。建議您使用用戶端程式庫，因為這些程式庫會為您處理這項作業。
CUSTOMER_NOT_FOUND	摘要 找不到標頭中提供的客戶 ID 帳戶。 常見原因 嘗試存取剛建立的帳戶，但後端尚未建立該帳戶。 如何處理 先等待五分鐘，然後每隔 30 秒重試一次。 預防秘訣 建立帳戶後，請稍候幾分鐘再對其發出要求。
GOOGLE_ACCOUNT_COOKIE_INVALID	摘要 要求標頭中的存取權杖無效或已過期。 常見原因 存取權杖已失效。 如何處理 要求新的權杖。如果您使用我們的用戶端程式庫，請參閱相關說明文件，瞭解如何重新整理權杖。 預防秘訣 儲存並重複使用存取權杖，直到權杖過期。
NOT_ADS_USER	摘要 用來產生存取權杖的 Google 帳戶未與任何 Google Ads 帳戶建立關聯。 常見原因 您提供的登入資訊對應的 Google 帳戶未啟用 Google Ads。 如何處理 請務必使用有效的 Google Ads 帳戶 (通常是管理員帳戶) 登入 OAuth 流程。您也可以邀請 Google 帳戶存取現有的 Google Ads 帳戶，方法是登入管理員帳戶，選取相關客戶或管理員帳戶，前往 Tools and Settings > Access and security，然後新增 Google 帳戶電子郵件地址。 預防秘訣 不適用
OAUTH_TOKEN_INVALID	摘要 標頭中的 OAuth 存取權杖無效。 常見原因 您透過 HTTP 標頭傳遞的存取權杖不正確。 如何處理 不適用 預防秘訣 請確認您已傳遞與帳戶相關聯的正確存取權杖。有時會與更新權杖和授權碼混淆。如要取得可存取管理員帳戶下所有客戶帳戶的認證，請務必取得管理員帳戶的更新權杖。請參閱使用者驗證指南。

AuthorizationError
CLOUD_PROJECT_NOT_APPROVED_FOR_PRODUCTION	摘要 Google Cloud 雲端專案僅具備測試存取權，無法用於存取正式版帳戶。 常見原因 使用測試存取層級的 Google Cloud 雲端專案，對非測試 (正式版) Google Ads 帳戶提出要求。(在 API 24 以下版本中，這個條件會傳回 AuthorizationError.ACTION_NOT_PERMITTED。) 如何處理 如果您正在進行測試，請確認要求指定的是測試帳戶。如要存取正式版 Google Ads 帳戶，請在 Google Ads API 總覽頁面中查看 Google Cloud 專案的存取層級，並將專案的存取層級升級為探索者、基本或標準存取權。 預防秘訣 不適用
CUSTOMER_NOT_ENABLED	摘要 客戶帳戶未啟用，因此無法存取。 常見原因 如果客戶帳戶尚未完成註冊或已停用，就會發生這種情況。 如何處理 登入 Google Ads 使用者介面，確認您已完成這個帳戶的註冊程序。如要瞭解如何重新啟用已停用的帳戶，請參閱「重新啟用已取消的 Google Ads 帳戶」一文。 預防秘訣 您可以主動檢查客戶帳戶是否已停用，方法是查看狀態是否為「已取消」。
USER_PERMISSION_DENIED	摘要 授權客戶無權存取操作客戶。 常見原因 以具備管理員帳戶存取權的使用者身分進行驗證，但未在要求中指定 login-customer-id。 如何處理 不適用 預防秘訣 請指定不含連字號的管理員帳戶 ID (login-customer-id)，例如 -。用戶端程式庫已內建這項支援功能。

BiddingError
BID_TOO_MANY_FRACTIONAL_DIGITS	摘要 出價金額不是帳戶幣別最小單位的整數倍。舉例來說，0.015 美元 (15000 微元) 不是有效出價。 常見原因 不適用 如何處理 不適用 預防秘訣 確認出價是帳戶貨幣最小單位的倍數。
BID_TOO_BIG	摘要 即使出價在廣告活動預算範圍內，系統仍會傳回錯誤。 常見原因 不適用 如何處理 不適用 預防秘訣 確認帳戶是否參與 Google Grants 廣告計畫。如果是，請將單次點擊出價限制在計畫規定的上限。

CampaignBudgetError
MONEY_AMOUNT_LESS_THAN_CURRENCY_MINIMUM_CPC	摘要 預算金額過低。 常見原因 不適用 如何處理 不適用 預防秘訣 確認預算金額大於或等於帳戶幣別的最小單位。
NON_MULTIPLE_OF_MINIMUM_CURRENCY_UNIT	摘要 從微量轉換為帳戶幣別的金額時，預算金額的小數位數過多。 常見原因 不適用 如何處理 不適用 預防秘訣 確認預算金額可由帳戶幣別的最小單位整除。

CampaignError
DUPLICATE_CAMPAIGN_NAME	摘要 正在新增或重新命名廣告活動，但已有其他廣告活動使用這個名稱。 常見原因 建立新廣告活動時，使用現有有效或已暫停廣告活動的名稱。 如何處理 記錄錯誤並向使用者顯示錯誤訊息，視需要建議不重複的廣告活動名稱，或顯示使用中的名稱清單。 預防秘訣 不適用
CANNOT_SET_CAMPAIGN_KEYWORD_MATCH_TYPE	摘要 嘗試在已啟用 AI Max 的廣告活動中，變更廣告活動層級關鍵字比對類型設定。 常見原因 啟用 AI Max 後，系統預設會將所有關鍵字視為廣泛比對，因此廣告活動層級的廣泛比對設定會淘汰。嘗試設定或修改這個欄位會觸發錯誤。 如何處理 建議使用者採用廣告群組層級的「disable_search_term_matching」參數，而非在廣告活動層級設定廣泛比對。 預防秘訣 如果 `ai_max_setting.enable_ai_max` 設為 `true`，請避免在廣告活動中將 `keyword_match_type` 設為 `BROAD` (或任何其他值)。請使用 `disable_search_term_matching`，在廣告群組層級切換搜尋字詞比對。

CriterionError
KEYWORD_HAS_INVALID_CHARS	摘要 新增或編輯含有無效字元的關鍵字。 常見原因 在關鍵字中使用特殊字元，例如 ! @ % *。 如何處理 不適用 預防秘訣 請勿在關鍵字中使用任何不允許的字元。請參閱「新增關鍵字」。

DistinctError
DUPLICATE_ELEMENT	摘要 要求包含兩個相同且多餘的參數。 常見原因 不適用 如何處理 不適用 預防秘訣 請先移除重複項目 (作業、參數、清單元素)，再提出要求。找出具有 DistinctElements 限制的欄位。

InternalError
DEADLINE_EXCEEDED	摘要 要求逾時，無法及時完成並傳回回應。 常見原因 搜尋要求產生的回應過大，或變更要求過大而無法處理。 如何處理 請等候約 30 秒後，再重新提出這項要求。如果錯誤持續發生，請嘗試將要求拆分為多個較小的要求，以便更快完成。 預防秘訣 請參閱「區隔」一節，瞭解這項功能對回應大小的影響。請注意 gRPC 傳輸層的限制。
INTERNAL_ERROR	摘要 處理要求時發生未預期的錯誤。 常見原因 API 因錯誤而無法正常運作。 如何處理 請以指數輪詢方式，重試因這項錯誤而失敗的要求。 預防秘訣 不適用
TRANSIENT_ERROR	摘要 發生暫時性內部錯誤，應執行重試。 常見原因 API 內部發生暫時性問題時，就會出現這項錯誤。 如何處理 請以指數輪詢方式，重試因這項錯誤而失敗的要求。 預防秘訣 不適用

InvalidGrantError
invalid_grant (malformed auth code)	摘要 用來交換 OAuth 權杖的授權碼格式有誤。 常見原因 如果使用者已獲准存取要求應用程式，系統卻嘗試為該使用者產生更新權杖，就會發生這種情況。舉例來說，如果針對相同的 OAuth 用戶端憑證和授權使用者，多次執行產生使用者憑證範例，就可能發生這種情況。 如何處理 如要為特定授權使用者和 OAuth 用戶端憑證組合重新產生更新權杖，請撤銷現有的更新權杖。請注意，撤銷權杖後，該權杖就無法用於存取 Google Ads API，且使用該更新權杖產生的所有存取權杖都會失效。 預防秘訣 請務必將更新權杖儲存在安全的位置，以免需要重新產生。

MutateError
RESOURCE_NOT_FOUND	摘要 要求參照的資源不存在。 常見原因 要求嘗試變更或參照不存在或已移除的資源。或資源名稱格式不正確。 如何處理 提交變更要求前，請先使用搜尋要求擷取現有資源的資源名稱。請參閱用戶端程式庫指南，其中包含如何以各種支援語言建構有效資源名稱的說明文件 預防秘訣 請勿手動建立資源名稱。使用用戶端程式庫提供的其中一種輔助方法。

NotEmptyError
EMPTY_LIST	摘要 必要清單空白。 常見原因 將空白作業清單傳遞至 mutate 方法。 如何處理 不適用 預防秘訣 不適用

QuotaError
RESOURCE_EXHAUSTED	摘要 超過系統頻率限制。 常見原因 不適用 如何處理 不適用 預防秘訣 在要求之間設定短暫延遲，或在較少的要求中合併更多作業。

RangeError
TOO_LOW	摘要 值低於允許的最小值。 常見原因 忘記指定 ID，導致傳入 0 值。 如何處理 不適用 預防秘訣 請注意 API 參考資料中記載的任何範圍限制。

RequestError
INVALID_INPUT	摘要 要求格式錯誤。 常見原因 要求的網址或內容格式錯誤。 如何處理 不適用 預防秘訣 不適用
REQUIRED_FIELD_MISSING	摘要 要求缺少必要資訊。 常見原因 嘗試新增實體時，未填寫必填欄位。 如何處理 記錄錯誤，並向使用者顯示錯誤訊息。錯誤的 fieldPath 屬性會指出缺少哪個欄位。 預防秘訣 請參閱 API 參考資料，瞭解哪些是必填欄位。

ResourceCountLimitExceededError
RESOURCE_LIMIT	摘要 要求嘗試建立的資源會導致該資源總數超過指定限制。 常見原因 在特定情境中，可存在的資源數量有多項限制。 如何處理 查看系統限制，找出遇到的限制。請重複使用現有資源，或移除資源來騰出空間建立新資源。 預防秘訣 使用搜尋查詢，監控有限制的資源數量。

StringLengthError
TOO_LONG	摘要 指派給指定欄位的字串長度超過上限。 常見原因 廣告的廣告標題或說明含有過多文字。 如何處理 找出遇到的限制，據此修改字串，然後重新傳送要求。 預防秘訣 請注意字串長度限制。