常见错误

本页面列出了常见错误，并提供了有关如何预防和处理这些错误的提示。如需查看完整的错误列表，请参阅错误参考文档、了解 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	摘要 此运算符不能与广告子类一起使用。 常见原因 尝试修改广告的 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	摘要 单个请求中的两项操作包含一项针对具有相同二进制数据的素材资源的创建操作。 常见原因 包含相同二进制数据的重复创建操作的 mutate 请求。 如何处理 在单独的请求中创建素材资源，然后在后续请求中链接到该素材资源；或者，在同一请求中使用临时 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 对应的账号。 常见原因 尝试访问刚刚创建的账号，但该账号尚未在后端建立。 如何处理 先等待 5 分钟，然后每隔 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 版本 v24 及更低版本中，此条件返回 AuthorizationError.ACTION_NOT_PERMITTED。） 如何处理 如果您正在进行测试，请确保您的请求针对的是测试账号。如果您想访问正式版 Google Ads 账号，请在 Google Ads API 概览页面上查看 Google Cloud 项目的访问权限级别，然后将项目的访问权限级别升级为“探索者”“基本”或“标准”访问权限。 预防建议 不适用
CUSTOMER_NOT_ENABLED	摘要 客户账号处于未启用状态，因此无法访问。 常见原因 当客户账号未完成注册或已被停用时，会发生此错误。 如何处理 登录 Google Ads 界面，并确保您已完成此账号的注册流程。对于已停用的账号，请参阅重新激活已撤销的 Google Ads 账号。 预防建议 您可以主动检查客户账号是否已停用，方法是检查状态是否为 CANCELLED。
USER_PERMISSION_DENIED	摘要 授权客户无法访问正在操作的客户。 常见原因 以有权访问经理账号的用户的身份进行身份验证，但在请求中未指定 login-customer-id。 如何处理 不适用 预防建议 将 login-customer-id 指定为不含连字符的经理账号 ID (-)。客户端库内置了对此的支持。

BiddingError
BID_TOO_MANY_FRACTIONAL_DIGITS	摘要 出价的值不是账号所用币种最小单位的整数倍。例如，0.015 美元（以微为单位表示为 15000）不是有效的出价。 常见原因 不适用 如何处理 不适用 预防建议 验证出价是否是相应账号所用币种的最小单位的倍数。
BID_TOO_BIG	摘要 即使出价在广告系列预算范围内，也会返回此错误。 常见原因 不适用 如何处理 不适用 预防建议 检查该账号是否参与了 Google 广告助公益计划。如果是，请将每次点击费用出价限制为计划规定的最高出价。

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	摘要 请求超时，无法及时完成并返回响应。 常见原因 发出的搜索请求生成的响应过大，或者 mutate 请求过大，无法处理。 如何处理 等待大约 30 秒后，重新尝试发出请求。如果错误仍然存在，请尝试将请求分解为多个较小的请求，以便更快地完成这些请求。 预防建议 查看分段，了解它如何影响回答的大小。请注意 gRPC 传输层限制。
INTERNAL_ERROR	摘要 处理请求时发生了意外。 常见原因 由于存在 bug，该 API 无法正常运行。 如何处理 使用指数退避算法重试因出现此错误而失败的所有请求。 预防建议 不适用
TRANSIENT_ERROR	摘要 发生了暂时性内部错误，应执行重试。 常见原因 当 API 在内部遇到临时问题时，会发生此错误。 如何处理 使用指数退避算法重试因出现此错误而失败的所有请求。 预防建议 不适用

InvalidGrantError
invalid_grant (malformed auth code)	摘要 交换为 OAuth 令牌的授权代码格式有误。 常见原因 当尝试为已获授权访问请求应用的用户生成刷新令牌时，就会发生这种情况。例如，如果针对同一 OAuth 客户端凭据和授权用户多次运行生成用户凭据示例，就会发生这种情况。 如何处理 如需为给定的授权用户和 OAuth 客户端凭据组合重新生成刷新令牌，请撤消现有刷新令牌。请注意，撤消令牌会导致该令牌无法用于 Google Ads API 访问，并使刷新令牌曾用于生成的所有访问令牌失效。 预防建议 请务必将刷新令牌存储在安全的位置，以免需要重新生成。

MutateError
RESOURCE_NOT_FOUND	摘要 相应请求所引用的资源无法找到。 常见原因 该请求尝试变异或以其他方式引用不存在或已被移除的资源。或者，相应资源的资源名称格式有误。 如何处理 在提交 mutate 请求之前，使用搜索请求检索现有资源的资源名称。查看我们的客户端库指南，其中包含有关如何以每种受支持的语言构建有效资源名称的文档 预防建议 请勿手动创建资源名称。使用客户端库提供的辅助方法之一。

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	摘要 分配给指定字段的字符串超过了长度上限。 常见原因 广告的标题或广告内容描述包含的文字过多。 如何处理 确定遇到的限制，相应地修改字符串，然后重新发送请求。 预防建议 请注意字符串长度限制。