エラーの原因には、不適切な環境設定やソフトウェアのバグ、ユーザーからの無効な入力があります。いずれにしても、そのエラーの原因を突き止めて、コードを修正したり、ユーザーによるエラーを処理するロジックを追加したりする必要があります。このガイドでは 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"}}]}
例外メッセージを調べて、エラーの原因を調べます。レスポンスを確認してから、リクエストを調べて、考えられる原因を探します。一部の 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 に誤った情報を提供している可能性があります。デバッグを支援するために、Eclipse（主に Java の開発に使用される無料のオープンソース IDE ですが、他の言語用のプラグインもあります）などの統合開発環境（IDE）の使用を強くおすすめします。IDE では、ブレークポイントを設定したり、コードを 1 行ごとにステップ実行したりすることができます。
リクエストがアプリケーションの入力と一致していることを確認します（たとえば、キャンペーンの名前がリクエストと一致するようにしてください）。実施するアップデートと一致するフィールド マスクを送信します。Google Ads API ではスパース アップデートがサポートされています。mutate リクエストでフィールド マスクからフィールドを省略すると、API で無視されます。オブジェクトを取り出し、変更を加えて元に戻すアプリケーションの場合、更新をサポートしていないフィールドに書き込んでいる可能性があります。フィールドを更新できるタイミングや条件に制限があるかどうかについては、リファレンス ドキュメントでフィールドの説明を確認してください。
[[["わかりやすい","easyToUnderstand","thumb-up"],["問題の解決に役立った","solvedMyProblem","thumb-up"],["その他","otherUp","thumb-up"]],[["必要な情報がない","missingTheInformationINeed","thumb-down"],["複雑すぎる / 手順が多すぎる","tooComplicatedTooManySteps","thumb-down"],["最新ではない","outOfDate","thumb-down"],["翻訳に関する問題","translationIssue","thumb-down"],["サンプル / コードに問題がある","samplesCodeIssue","thumb-down"],["その他","otherDown","thumb-down"]],["最終更新日 2025-09-05 UTC。"],[[["\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."]]
