问题排查
使用集合让一切井井有条
根据您的偏好保存内容并对其进行分类。
ondemand_video
视频:观看 2019 年研讨会上的错误处理主题演讲
不正确的环境设置、软件中的错误或用户的无效输入都会导致出现错误。无论何种原因,您都需要进行问题排查,并修复代码或添加逻辑以便处理用户错误。本指南探讨了 Google Ads API 错误问题排查方面的一些最佳做法。
确保网络连接正常
确保您可以访问 Google Ads API 并已进行正确的设置。如果您的响应返回任何 HTTP 错误,请确保谨慎处理这些错误,并确保可以通过代码访问您要使用的服务。
您的凭据已嵌入到请求中,以便相关服务对您进行身份验证。熟悉 Google Ads API 请求和响应的结构,尤其是您要在不使用客户端库的情况下处理调用时。每个客户端库都附带了有关如何在配置文件中添加凭据的具体说明(请参阅客户端库的 README 文件)。
确认您使用的是正确凭据。我们的快速入门逐步说明了如何完成所需的正确设置。例如,下面的响应故障表明用户发送了无效的身份验证凭据:
{
"error": {
"code": 401,
"message": "Request had invalid authentication credentials. Expected OAuth 2 access token, login cookie or other valid authentication credential. Visit https://developers.google.com/identity/sign-in/web/devconsole-project.",
"status": "UNAUTHENTICATED",
"details": [
{
"@type": "type.googleapis.com/google.rpc.DebugInfo",
"detail": "Authentication error: 2"
}
]
}
}
如果您在按照上述步骤操作后仍然遇到问题,那么应该深入了解如何对 Google Ads API 错误进行问题排查。
确定问题
Google Ads API 通常将错误报告为 JSON 故障对象,其中包含响应中的一系列错误。这些对象会提供错误代码以及详细说明错误发生原因的消息。它们是帮助您了解可能存在什么问题的第一手资料。
{
"errors": [
{
"errorCode": { "fieldMaskError": "FIELD_NOT_FOUND" },
"message": "The field mask contained an invalid field: 'keyword/matchtype'.",
"location": { "operationIndex": "1" }
}
]
}
我们的所有客户端库都会引发封装有响应中的错误的异常。捕获这些异常并在日志或问题排查屏幕上呈现相关信息是一个很好的入手点。通过将这些信息与应用中记录的其他事件整合在一起,就可以很好地概要了解引发问题的可能原因。发现日志中存在的错误后,您就需要弄清楚它的含义。
研究错误
请参阅我们的常见错误文档,其中描述了最常遇到的错误,并且对错误消息、相关 API 引用以及如何避免或处理错误进行了说明。
如果我们的常见错误文档并未明确提及您遇到的错误,请参阅我们的参考文档并查找错误字符串。
搜索我们的支持渠道,以了解其他开发者分享的 API 使用经验。其他人可能已经遇到并解决了您遇到的问题。
如果您遇到尚无相关记录的错误,请通过论坛告诉我们。
如需获取有关验证或账号限制问题排查方面的帮助,请访问 Google Ads 帮助中心,因为 Google Ads API 继承了核心 Google Ads 产品的规则和限制。
在排查应用的问题时,偶尔也可看看博文这一很好的参考资料。
在研究错误之后,接下来应该确定错误的根本原因。
找出原因
查看异常消息可确定错误的原因。在查看响应后,请查看请求,了解产生错误的可能原因。某些 Google Ads API 错误消息会在 GoogleAdsError
的 location
字段中包含一个 fieldPathElements
,表明错误发生在请求中的何处。例如:
{
"errors": [
{
"errorCode": {"criterionError": "CANNOT_ADD_CRITERIA_TYPE"},
"message": "Criteria type can not be targeted.",
"trigger": { "stringValue": "" },
"location": {
"operationIndex": "0",
"fieldPathElements": [ { "fieldName": "keyword" } ]
}
}
]
}
在排查问题时,可能是您的应用向 API 提供了错误的信息。我们强烈建议您使用交互式开发环境 (IDE),例如 Eclipse(一款免费的开源 IDE,主要用于开发 Java,但也有其他语言的插件),以帮助您进行调试。它可让您设置断点并逐行验证代码。
仔细检查以确保请求与您的各项应用输入相匹配,例如,广告系列的名称可能无法与请求成功匹配。请确保您发送的字段掩码与您要进行的更新相匹配,因为 Google Ads API 支持稀疏更新。
在 mutate 请求中,忽略字段掩码中的某个字段表示 API 不会对其进行处理。如果您的应用检索一个对象,对其进行更改然后发回,那么可能是因为您对一个不支持更新的字段执行了写入操作。请查看参考文档中的字段说明,了解在何时或是否可以更新该字段。
如何获取帮助
您不可能总是仅凭一己之力找出问题,然后解决问题。
在论坛上提问可让数以千计的开发者看到您的问题,而这些开发者可能遇到过相同的问题。
请尽量在您的查询中包含尽可能多的信息。
建议提供以下信息:
- 经过整理的 JSON 请求和响应。请务必移除敏感信息,如您的开发者令牌或 AuthToken。
- 代码段。如果您遇到与特定语言相关的问题,或者需要有关 API 使用方面的帮助,可以提供代码段来解释您的操作。
- RequestId。如果您提出的请求是针对生产环境的,那么这一信息可帮助 Google 开发者关系团队成员找到您的请求。我们建议您在日志中注册 requestId,使其作为属性包含在异常中,这些异常封装了响应错误,而且比单独的 requestId 包含更多上下文。
- 其他信息在问题排查时也很有用,如运行时/解释器版本以及平台。
解决问题
现在您已经确定问题并知道了解决方案,接下来您应该在测试账号中进行更改并测试修复结果(这是推荐的做法;但如果错误仅适用于特定生产账号中的数据,请在生产环境中进行)。
考虑分享
如果您在论坛中发布了一个关于之前没有出现过的错误的问题,并且您已经找到了解决方案,请考虑将其添加到讨论帖中。这样一来,开发者下次遇到同样的问题时就能够立即加以解决。
后续步骤
现在您已经解决了问题,那么是否注意到有什么方法可以改进代码,从而提前避免出现此类问题呢?
设计一组恰当的单元测试有助于显著提高代码的质量和可靠性。此外,这还可以加快新的更改的测试过程,确保它们不会破坏以前的功能。对于显示问题排查所需的全部数据而言,制定满意的错误处理策略也很关键。
如未另行说明,那么本页面中的内容已根据知识共享署名 4.0 许可获得了许可,并且代码示例已根据 Apache 2.0 许可获得了许可。有关详情,请参阅 Google 开发者网站政策。Java 是 Oracle 和/或其关联公司的注册商标。
最后更新时间 (UTC):2025-08-26。
[null,null,["最后更新时间 (UTC):2025-08-26。"],[[["\u003cp\u003eThis guide provides best practices for troubleshooting errors when using the Google Ads API, covering connectivity checks, error identification, and resolution strategies.\u003c/p\u003e\n"],["\u003cp\u003eYou can determine the problem by examining the JSON error objects in the API response, researching the error code in the documentation or support channels, and analyzing the request for potential causes.\u003c/p\u003e\n"],["\u003cp\u003eLeverage IDEs for debugging, ensure accurate request data, and consult the documentation for field restrictions to effectively locate the root cause of errors.\u003c/p\u003e\n"],["\u003cp\u003eIf independent troubleshooting proves insufficient, seek assistance through the Google Ads API forum, providing comprehensive information to facilitate resolution.\u003c/p\u003e\n"],["\u003cp\u003eAfter resolving the error, enhance your code with unit tests and robust error handling to prevent similar issues in the future.\u003c/p\u003e\n"]]],[],null,["# Troubleshooting\n\nondemand_video\n[Video: Check out the error handling talk from the 2019 workshop](https://www.youtube.com/watch?v=J9zVoWT7twk&list=None&start=1158)\n\nErrors can be caused by an incorrect environment setup, a bug in\nyour software, or invalid input from a user. No matter the source, you will\nneed to troubleshoot the issue and either fix your code or add logic to handle\nthe user error. This guide discusses some best practices when troubleshooting\nerrors from the Google Ads API.\n\nEnsuring connectivity\n---------------------\n\n1. Make sure you have access to the Google Ads API and a correct setup. If your\n response returns any HTTP errors, make sure you address those carefully and\n that you are reaching the services you intend to use from your code.\n\n2. Your credentials are embedded in your\n [request](/google-ads/api/docs/concepts/call-structure#request_headers) in order for the\n services to authenticate you. Familiarize yourself with the structure of Google Ads API\n requests and responses, especially if you are going to handle calls without\n using the client libraries. Each client library is shipped with specific\n instructions on how to include your credentials in the config file (consult the\n client library's README).\n\n3. Verify that you are using the correct credentials. Our\n [Quickstart](/google-ads/api/docs/start) takes you through the process of acquiring the\n correct set you need. For example, the following response failure shows that the\n user has sent invalid authentication credentials:\n\n {\n \"error\": {\n \"code\": 401,\n \"message\": \"Request had invalid authentication credentials. Expected OAuth 2 access token, login cookie or other valid authentication credential. Visit https://developers.google.com/identity/sign-in/web/devconsole-project.\",\n \"status\": \"UNAUTHENTICATED\",\n \"details\": [\n {\n \"@type\": \"type.googleapis.com/google.rpc.DebugInfo\",\n \"detail\": \"Authentication error: 2\"\n }\n ]\n }\n }\n\nIf you've followed these steps and are still having issues, it's time to dive\ninto troubleshooting the Google Ads API errors.\n\nDetermining the problem\n-----------------------\n\nThe Google Ads API generally reports errors as a JSON failure object, containing\na list of errors in the response. These objects provide an error code as well as\na message elaborating on why it occurred. They are your first signals of what\nthe problem might be. \n\n {\n \"errors\": [\n {\n \"errorCode\": { \"fieldMaskError\": \"FIELD_NOT_FOUND\" },\n \"message\": \"The field mask contained an invalid field: 'keyword/matchtype'.\",\n \"location\": { \"operationIndex\": \"1\" }\n }\n ]\n }\n\nAll our [client libraries](/google-ads/api/docs/client-libs) throw exceptions that\nencapsulate errors in the response. Capturing these exceptions and\nprinting out the messages in a log or a troubleshooting screen is a great way\nto start. Integrating this information with the other logged events in your\napplication offers a good overview of what might be triggering the problem.\nOnce you've identified the error in the logs, you'll need to figure out what\nit means.\n\nResearching the error\n---------------------\n\n1. Refer to our [Common Errors](/google-ads/api/docs/best-practices/common-errors)\n documentation, which covers the most frequently encountered errors. It\n describes the error message, relevant API references, and how to avoid or\n handle the error.\n\n2. If our common errors documentation doesn't specifically mention the error,\n consult our [reference documentation](/google-ads/api/reference/rpc) and look for the error string.\n\n3. Search our [support channels](/google-ads/api/support) to gain access to other\n developers sharing their experiences with the API. Someone else may have\n run into---and solved---the problem you are having.\n\n4. If you encounter any errors that are not documented, bring this to\n our attention on the forum.\n\n5. Go to the [Google Ads Help Center](//support.google.com/google-ads/)\n for help troubleshooting validation or account limit issues---the\n Google Ads API inherits the rules and limitations of the core Google Ads product.\n\n6. [Blog posts](//ads-developers.googleblog.com/search/label/google_ads_api)\n will on occasion be a good reference when troubleshooting your application.\n\nAfter researching the error, it's time to determine the root cause.\n\nLocating the cause\n------------------\n\nCheck the exception message to determine the cause of the error. After looking\nat the response, check the request for a possible cause. Some Google Ads API error\nmessages include a [`fieldPathElements`](/google-ads/api/reference/rpc/v21/ErrorLocation#field_path_elements%5B%5D)\nin the [`location`](/google-ads/api/reference/rpc/v21/GoogleAdsError#location) field of the\n[`GoogleAdsError`](/google-ads/api/reference/rpc/v21/GoogleAdsError), indicating where\nin the request the error occurred. For example: \n\n {\n \"errors\": [\n {\n \"errorCode\": {\"criterionError\": \"CANNOT_ADD_CRITERIA_TYPE\"},\n \"message\": \"Criteria type can not be targeted.\",\n \"trigger\": { \"stringValue\": \"\" },\n \"location\": {\n \"operationIndex\": \"0\",\n \"fieldPathElements\": [ { \"fieldName\": \"keyword\" } ]\n }\n }\n ]\n }\n\nWhen troubleshooting an issue, it may be that your application is providing the\nwrong information to the API. We strongly encourage the use of an Interactive\nDevelopment Environment (IDE) such as [Eclipse](//eclipse.org/) (a free\nand open source IDE which is primarily used to develop Java, but has plugins for\nother languages) to aid you in debugging. It lets you set breakpoints and step\nthrough your code line by line.\n\nDouble-check to make sure the request matches your application inputs (for\nexample the Campaign's name might not be making it to the request). Make sure\nyou send a\n[field mask](/protocol-buffers/docs/reference/google.protobuf#field-mask)\nthat matches the updates you want to make--the Google Ads API supports sparse updates.\nOmitting a field from the field mask in a mutate request indicates the API\nshould leave it alone. If your application retrieves an object, makes a change,\nand sends it back, you may be writing to a field that does not\nsupport updating. Check the field's description in the [reference\ndocumentation](/google-ads/api/reference/rpc) to see if there are any restrictions on when or if you\ncan update the field.\n\n### How to get help\n\nIt's not always possible to identify and solve the problem on your own.\nAsking on the [forum](//groups.google.com/g/adwords-api) exposes\nyour question to thousands of developers who may have had to deal with the same\nissue.\n\nTry to include as much information as you can in your queries.\nRecommended items include:\n\n- Sanitized JSON request and response. Make sure to remove sensitive information such as your developer token or AuthToken.\n- Code snippets. If you are having a language-specific problem or are requesting help working with the API, include a snippet of code to help explain what you are doing.\n- RequestId. This enables Google Developer Relations team members to locate your request if made against the production environment. We recommend registering in your logs the requestId included as a property in the exceptions that encapsulate response errors, as well as more context than requestId alone.\n- Additional information, such as runtime/interpreter version and platform can also be useful when troubleshooting.\n\nFixing the problem\n------------------\n\nNow that you've figured out the problem and come up with a solution, it's time\nto make your change and test the fix against a test account (preferred) or\nproduction (if the bug only applies to data in a specific production account).\n\n### Consider Sharing\n\nIf you have posted a question in the forum regarding an error that hadn't been\nsurfaced there before and you have found the solution, consider adding it to the\nthread. Next time a developer has the same problem they'll be able to solve it\nright away.\n\n### Next Steps\n\nNow that you've solved this problem, did you notice any ways to improve your\ncode to avoid this in the first place?\n\nCreating a good set of unit tests helps improve code quality and reliability\nconsiderably. It also speeds up the process of testing new changes to ensure\nthey didn't break previous functionality. A good error handling strategy is also\nkey in surfacing all the necessary data for troubleshooting."]]