Understand API errors

This guide explains how the Google Ads API handles and communicates errors. Understanding the structure and meaning of API errors is crucial for building robust applications that can gracefully handle issues, from invalid input to temporary service unavailability.

The Google Ads API follows the standard Google API error model, which is based on gRPC Status codes. Each API response that results in an error includes a Status object containing:

• A numeric error code.
• An error message.
• Optional, additional error details.

Canonical error codes

The Google Ads API uses a set of canonical error codes defined by gRPC and HTTP. These codes provide a high-level indication of the error type. You should always check this numeric code first to understand the fundamental nature of the problem.

The following table summarizes the most common codes you might encounter when using the Google Ads API:

For more details on these codes, refer to API Design Guide - Error codes.

Understand error details

Beyond the top-level code, the Google Ads API provides more specific error information within the details field of the Status object. This field often contains a GoogleAdsFailure proto, which includes a list of individual GoogleAdsError objects.

Each GoogleAdsFailure object contains:

• errors: A list of GoogleAdsError objects, each detailing a specific error that occurred.
• request_id: A unique ID for the request, useful for debugging and support purposes.

Each GoogleAdsError object provides:

• errorCode: A more granular, Google Ads API-specific error code, such as AuthenticationError.NOT_ADS_USER.
• message: A human-readable description of the specific error.
• trigger: The value that caused the error, if applicable.
• location: Describes where in the request the error occurred, including field paths.
• details: Additional error details, such as unpublished error reasons.

Example of error details

When you receive an error, your client library will allow you to access these details. For example, an INVALID_ARGUMENT (Code 3) might have GoogleAdsFailure details like this:

{
  "code": 3,
  "message": "The request was invalid.",
  "details": [
    {
      "@type": "type.googleapis.com/google.ads.googleads.v17.errors.GoogleAdsFailure",
      "errors": [
        {
          "errorCode": {
            "fieldError": "REQUIRED"
          },
          "message": "The required field was not present.",
          "location": {
            "fieldPathElements": [
              { "fieldName": "operations" },
              { "fieldName": "create" },
              { "fieldName": "name" }
            ]
          }
        },
        {
          "errorCode": {
            "stringLengthError": "TOO_SHORT"
          },
          "message": "The provided string is too short.",
          "trigger": {
            "stringValue": ""
          },
          "location": {
            "fieldPathElements": [
              { "fieldName": "operations" },
              { "fieldName": "create" },
              { "fieldName": "description" }
            ]
          }
        }
      ]
    }
  ]
}

In this example, despite the top-level INVALID_ARGUMENT, the GoogleAdsFailure details tell you that the name and description fields caused the issue and why (REQUIRED and TOO_SHORT, respectively).

Locate error details

How you access error details depends on whether you are using standard API calls, partial failure, or streaming.

Standard and streaming API calls

When an API call fails without using partial failure, including streaming calls, the GoogleAdsFailure object is returned as part of the trailing metadata in the gRPC response headers. If you're using REST for standard calls, GoogleAdsFailure is returned in the HTTP response. Client libraries typically surface this as an exception with a GoogleAdsFailure attribute.

Partial failure

If you are using partial failure, errors for failed operations are returned in the partial_failure_error field of the response, not in the response headers. In this case, the GoogleAdsFailure is embedded within a google.rpc.Status object in the response.

Batch jobs

For batch processing, errors for individual operations can be found by retrieving the batch job results after the job is complete. Each operation result will include a status field containing error details if the operation failed.

Request ID

The request-id is a unique string that identifies your API request and is essential for troubleshooting.

You can find the request-id in multiple places:

• GoogleAdsFailure: If an API call fails and GoogleAdsFailure is returned, it will contain a request_id.
• Trailing metadata: For both successful and failed requests, request-id is available in the trailing metadata of the gRPC response.
• Response headers: For both successful and failed requests, request-id is also available in the gRPC and HTTP response headers, with the exception of successful streaming requests.
• SearchGoogleAdsStreamResponse: For streaming requests, each SearchGoogleAdsStreamResponse message contains a request_id field.

When logging errors or contacting support, make sure to include the request-id to help with diagnosing issues.

Best practices for error handling

To build resilient applications, implement the following best practices:

1. Inspect error details: Always parse the details field of the Status object, specifically looking for GoogleAdsFailure. The granular errorCode, message, and location within GoogleAdsError provide the most actionable information for debugging and user feedback.

2. Differentiate client from server errors:

   • Client errors: Codes like INVALID_ARGUMENT, NOT_FOUND, PERMISSION_DENIED, FAILED_PRECONDITION, UNAUTHENTICATED. These require changes to the request or your application's state/credentials. Don't retry the request without addressing the issue.
   • Server errors: Codes like UNAVAILABLE, INTERNAL, DEADLINE_EXCEEDED, UNKNOWN. These suggest a temporary issue with the API service.

3. Implement a retry strategy:

   • When to retry: Retry only for transient server errors such as UNAVAILABLE, DEADLINE_EXCEEDED, INTERNAL, UNKNOWN, and ABORTED.
   • Exponential backoff: Use an exponential backoff algorithm to wait for increasing periods between retries. This helps avoid overwhelming an already stressed service. For example, wait 1s, then 2s, then 4s, continuing up to a maximum number of retries or total wait time.
   • Jitter: Add a small random amount of "jitter" to the backoff delays to prevent the "thundering herd" problem where many clients retry simultaneously.

4. Log thoroughly: Log the full error response, including all details, especially the request ID. This information is essential for debugging and for reporting issues to Google support if needed.

5. Provide user feedback: Based on the specific GoogleAdsError codes and messages, provide clear and helpful feedback to your application's users. For example, instead of just "An error occurred," you can say "Campaign name is required" or "The provided ad group ID was not found."

By following these guidelines, you can effectively diagnose and handle errors returned by the Google Ads API, leading to more stable and user-friendly applications.