Handle API errors

When you send a request to the Google Ads API, it might fail for various reasons. For example, you might provide an invalid argument, or your account might have reached its limit for creating new campaigns. In such cases, the API returns an error to let you know what went wrong.

This guide explains how to read and handle API errors so you can build more robust applications.

Error structure

If you are using one of our client libraries, API errors are surfaced as exceptions. These exceptions contain details that help you understand why the error occurred.

The Google Ads API returns error information in a standard format. If an error occurs, the response will contain a GoogleAdsFailure object. This object contains a list of individual GoogleAdsError objects, each detailing a specific error.

Each GoogleAdsError object provides:

• error_code: A specific error code that tells you the type of error, such as AuthenticationError.NOT_ADS_USER.
• message: A human-readable description of why the error occurred.
• trigger: The value that caused the error, like "1234".
• location: Details on which part of the request caused the error, such as a specific field name.

In addition to the list of errors, GoogleAdsFailure contains a requestId, which is a unique identifier for the API request that resulted in an error.

Example error

Here is an example of what an error looks like in JSON format. This error indicates that the name field of the ad_group at index 0 is missing from the request.

{
  "code": 3,
  "message": "Request contains an invalid argument.",
  "details": [
    {
      "@type": "type.googleapis.com/google.ads.googleads.v22.errors.GoogleAdsFailure",
      "errors": [
        {
          "errorCode": {
            "requestError": "REQUIRED_FIELD_MISSING"
          },
          "message": "Required field is missing",
          "location": {
            "fieldPathElements": [
              {
                "fieldName": "ad_group",
                "index": 0
              },
              {
                "fieldName": "name"
              }
            ]
          }
        }
      ],
      "requestId": "unique_request_id_12345"
    }
  ]
}

How to handle errors

If you encounter an error, here are the steps to take:

1. Examine the errors list: Look at each GoogleAdsError in the GoogleAdsFailure object. The error_code and message will tell you what went wrong.
2. Check the location: The location field can help you pinpoint where in your request the issue occurred.
3. Consult documentation: For specific error codes, check the common errors page or the full error code reference for more details on the error and how to fix it.
4. Adjust your request: Based on the error message, correct your API request. For example, if you see REQUIRED_FIELD_MISSING, make sure you provide that field in your request.
5. Log the request_id: If you are unable to figure out how to resolve an error and need to contact support through the forum, include the request_id. This ID helps Google engineers investigate your issue.

Next steps

• Review Common Errors for a list of frequent issues and their solutions.
• For more advanced error handling techniques, including retry logic and partial failure, see Understand API Errors.