오류는 잘못된 환경 설정, 소프트웨어의 버그 또는 사용자의 잘못된 입력으로 인해 발생할 수 있습니다. 소스와 관계없이 문제를 해결하고 코드를 수정하거나 사용자 오류를 처리하는 로직을 추가해야 합니다. 이 가이드에서는 Google Ads API의 오류를 해결할 때 몇 가지 권장사항을 설명합니다.
연결 보장
Google Ads API에 액세스할 수 있고 올바르게 설정되어 있는지 확인합니다. 대답에서 HTTP 오류가 반환되면 이를 신중하게 해결하고 코드에서 사용하려는 서비스에 연결하고 있는지 확인하세요.
서비스가 사용자를 인증할 수 있도록 사용자 인증 정보가 요청에 삽입됩니다. 클라이언트 라이브러리를 사용하지 않고 호출을 처리할 예정이라면 Google Ads API 요청 및 응답 구조를 숙지하세요. 각 클라이언트 라이브러리는 구성 파일에 사용자 인증 정보를 포함하는 방법에 관한 구체적인 안내와 함께 제공됩니다 (클라이언트 라이브러리의 README 참고).
올바른 사용자 인증 정보를 사용하고 있는지 확인합니다. Google의 빠른 시작에서는 필요한 올바른 세트를 획득하는 과정을 안내합니다. 예를 들어 다음 응답 실패는 사용자가 잘못된 인증 사용자 인증 정보를 전송했음을 보여줍니다.
{"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에 잘못된 정보를 제공할 수 있습니다. 디버깅에 도움이 되는 Eclipse (주로 Java를 개발하는 데 사용되지만 다른 언어용 플러그인이 있는 무료 오픈소스 IDE)와 같은 대화형 개발 환경 (IDE)을 사용하는 것이 좋습니다. 중단점을 설정하고 코드를 한 줄씩 단계별로 실행할 수 있습니다.
요청이 애플리케이션 입력과 일치하는지 다시 확인합니다 (예: 캠페인 이름이 요청에 포함되지 않을 수 있음). 업데이트하려는 항목과 일치하는 필드 마스크를 전송해야 합니다. Google Ads API는 스파스 업데이트를 지원합니다. 변이 요청의 필드 마스크에서 필드를 생략하면 API가 필드를 그대로 두어야 함을 나타냅니다. 애플리케이션이 객체를 가져와 변경한 후 다시 전송하는 경우 업데이트를 지원하지 않는 필드에 쓰고 있을 수 있습니다. 참조 문서에서 필드의 설명을 확인하여 필드를 업데이트할 수 있는 시기나 업데이트 가능 여부에 제한이 있는지 확인하세요.
지원을 받는 방법
혼자서 문제를 식별하고 해결할 수 없는 경우도 있습니다. 포럼에 질문하면 동일한 문제를 처리해야 했을 수 있는 수천 명의 개발자에게 질문이 표시됩니다.
질문에 최대한 많은 정보를 포함하세요. 다음의 항목을 포함할 것을 권장합니다.
삭제된 JSON 요청 및 응답입니다. 개발자 토큰이나 AuthToken과 같은 민감한 정보를 삭제해야 합니다.
코드 스니펫 언어 관련 문제가 있거나 API 사용에 대한 도움을 요청하는 경우, 내가 무엇을 하고 있는지 설명하는 데 도움이 되는 코드 스니펫을 포함하세요.
RequestId. 이렇게 하면 프로덕션 환경에 대해 요청이 이루어진 경우 Google 개발자 관계팀 구성원이 요청을 찾을 수 있습니다. 응답 오류를 캡슐화하는 예외에 속성으로 포함된 requestId와 requestId 이상의 컨텍스트를 로그에 등록하는 것이 좋습니다.
런타임/인터프리터 버전, 플랫폼과 같은 추가 정보도 문제 해결에 유용할 수 있습니다.
문제 해결
이제 문제를 파악하고 해결 방법을 마련했으므로 변경사항을 적용하고 테스트 계정 (권장) 또는 프로덕션 (버그가 특정 프로덕션 계정의 데이터에만 적용되는 경우)에 대해 수정사항을 테스트할 시간입니다.
공유 고려
이전에 포럼에 표시되지 않았던 오류에 관해 질문을 게시한 후 해결 방법을 찾은 경우 스레드에 추가하는 것이 좋습니다. 다음에 개발자가 동일한 문제가 발생하면 바로 해결할 수 있습니다.
다음 단계
이 문제를 해결했으니, 이 문제가 발생하지 않도록 코드를 개선할 방법이 있나요?
단위 테스트를 잘 만들면 코드 품질과 신뢰성을 크게 개선할 수 있습니다. 또한 이전 기능을 중단하지 않도록 새 변경사항을 테스트하는 프로세스를 가속화합니다. 또한 문제 해결에 필요한 모든 데이터를 표시하는 데도 적절한 오류 처리 전략이 중요합니다.
[[["이해하기 쉬움","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-08-26(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."]]
