常見錯誤

本頁面列出常見錯誤，並提供預防及處理這些錯誤的訣竅。如需完整的錯誤清單，請參閱錯誤參考資料、瞭解 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 秒重試一次。
預防秘訣 建立帳戶後，請稍候幾分鐘再對其發出要求。
摘要要求標頭中的存取權杖無效或已過期。
常見原因 存取權杖已失效。
如何處理 要求新權杖。如果您使用我們的用戶端程式庫，請參閱相關說明文件，瞭解如何重新整理權杖。
預防秘訣 儲存並重複使用存取權杖，直到權杖過期為止。
NOT_ADS_USER
摘要用來產生存取權杖的 Google 帳戶未與任何 Google Ads 帳戶建立關聯。
常見原因 您提供的登入資訊對應的 Google 帳戶未啟用 Google Ads。
如何處理 請務必使用有效的 Google Ads 帳戶 (通常是管理員帳戶) 登入 OAuth 流程。您也可以登入管理員帳戶，選取相關的客戶或管理員帳戶，然後前往 Tools and Settings > Access and security 並新增 Google 帳戶電子郵件地址，邀請該帳戶存取現有的 Google Ads 帳戶。
預防秘訣 不適用
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
摘要指派給指定欄位的字串長度超過上限。
常見原因 廣告的廣告標題或說明含有過多文字。
如何處理 找出遇到的限制，據此修改字串，然後重新傳送要求。
預防秘訣 請注意字串長度限制。

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