常見錯誤

本頁面列出常見錯誤，並提供預防及處理這些錯誤的提示。如需完整的錯誤清單，請參閱錯誤參考資料、瞭解 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 consent screen」(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。
預防秘訣 不適用
PARTNER_PROMOTION_ID_TYPE_INCOMPATIBLE
摘要合作夥伴促銷活動 ID 使用的 oneof 變體 (int_value 或 string_value) 不適用於帳戶的促銷活動整合。
常見原因 如果客戶的兌換整合需要 string_value 變化版本，請設定 promotion_asset.external_redeem_info.partner_promotion_id.int_value 欄位；如果整合需要 int_value 變化版本，請設定 string_value 欄位。
如何處理 更新建立要求，填入帳戶促銷活動整合接受的 ExternalPartnerId 變體 (int_value 或 string_value)。詳情請參閱「追蹤外部促銷活動兌換情形」。
預防秘訣 建立含有 external_redeem_info 欄位的 PromotionAsset 訊息前，請先確認銷售點 (POS) 兌換整合功能使用的促銷活動 ID 格式 (int_value 或 string_value)。

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 秒重試一次。
預防秘訣 帳戶建立後，請稍候幾分鐘再提出要求。
摘要要求標頭中的存取權杖無效或已過期。
常見原因 存取權杖已失效。
如何處理 要求新的權杖。如果您使用的是我們的用戶端程式庫，請參閱相關說明文件，瞭解如何重新整理權杖。
預防秘訣 儲存並重複使用存取權杖，直到權杖到期。
NOT_ADS_USER
摘要用來產生存取權杖的 Google 帳戶未與任何 Google Ads 帳戶建立關聯。
常見原因 您提供的登入資訊對應的 Google 帳戶未啟用 Google Ads。
如何處理 請務必使用有效的 Google Ads 帳戶 (通常是管理員帳戶) 登入，以進行 OAuth 流程。您也可以登入管理員帳戶，選取相關客戶或管理員帳戶，前往「Tools and Settings > Access and security」，然後新增 Google 帳戶電子郵件地址，邀請 Google 帳戶存取現有的 Google Ads 帳戶。
預防秘訣 不適用
OAUTH_TOKEN_INVALID
摘要標頭中的 OAuth 存取權杖無效。
常見原因 您透過 HTTP 標頭傳遞的存取權杖不正確。
如何處理 不適用
預防秘訣 請確認您已傳遞與帳戶相關聯的正確存取權杖。有時會與更新權杖和授權碼混淆。如要取得可存取管理員帳戶下所有客戶帳戶的憑證，請務必取得管理員帳戶的更新權杖。請參閱使用者驗證指南。

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

BiddingError
BID_TOO_MANY_FRACTIONAL_DIGITS
摘要出價金額不是帳戶幣別最小單位的整數倍。舉例來說，US$ 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
摘要新增或編輯含有無效字元的關鍵字。
常見原因 在關鍵字中使用特殊字元，例如 ! @ % *。
如何處理 不適用
預防秘訣 請確認關鍵字中沒有任何不允許的字元。請參閱「新增關鍵字」。

DemandGenCampaignError
CANNOT_ACTIVATE_MIGRATED_CAMPAIGN
摘要如果原始廣告活動尚未移除，或相同原始廣告活動的另一個遷移廣告活動已啟用，則無法啟用遷移的需求開發廣告活動。
常見原因 如果來源廣告活動未移除，或從相同來源廣告活動遷移的其他需求開發廣告活動已ENABLED，則將遷移的需求開發廣告活動status更新為ENABLED。在 API v25 以下版本中，這項條件會傳回 RequestError.UNKNOWN。
如何處理 啟用遷移後的需求開發廣告活動前，請先使用 CampaignOperation.remove 移除來源廣告活動 (可事先移除，或在同一個變更要求中移除)，並確認沒有其他從同一個來源廣告活動遷移的需求開發廣告活動正在放送。詳情請參閱「啟用已遷移的廣告活動」。
預防秘訣 如果您追蹤原始來源廣告活動和遷移後需求開發廣告活動的 ID，請先查詢 campaign.status，再將遷移後廣告活動的 status 設為 ENABLED，或在同一個變更要求中，為原始廣告活動加入 CampaignOperation.remove。

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

上一頁
其他方法
下一頁
範例