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:

gRPC code HTTP code Enum name Description Guidance
0 200 OK No error; indicates success. N/A
1 499 CANCELLED The operation was cancelled, typically by the client. Usually means the client stopped waiting. Check client-side timeouts.
2 500 UNKNOWN An unknown error occurred. More details might be in the error message or details. Treat as a server error. Can often be retried with backoff.
3 400 INVALID_ARGUMENT The client specified an invalid argument. This indicates a problem that prevents the API from processing the request, such as a malformed resource name or invalid value. Client error: Review your request parameters and ensure they meet API requirements. The error details usually provide information about which argument was invalid and how—use these details to fix the request. Don't retry without fixing the request.
4 504 DEADLINE_EXCEEDED The deadline expired before the operation could complete. Server error: Often transient. Consider retrying with exponential backoff.
5 404 NOT_FOUND Some requested entity, such as a campaign or ad group, was not found. Client error: Verify the existence and ID of the resources you are trying to access. Don't retry without correction.
6 409 ALREADY_EXISTS The entity the client attempted to create already exists. Client error: Avoid creating duplicate resources. Check if the resource exists before attempting to create it.
7 403 PERMISSION_DENIED The caller does not have permission to execute the specified operation. Client error: Check authentication, authorization, and user roles for the Google Ads account. Don't retry without resolving permissions.
8 429 RESOURCE_EXHAUSTED Either a resource has been exhausted (for example, you have exceeded your quota), or a system is overloaded. Client/Server error: Typically requires waiting. Implement exponential backoff and potentially reduce request rate. See API limits and quotas.
9 400 FAILED_PRECONDITION The operation was rejected because the system is not in a state required for the operation's execution. For example, a required field is missing. Client error: The request is valid, but the state is wrong. Review error details to understand the precondition failure. Don't retry without state correction.
10 409 ABORTED The operation was aborted, typically due to a concurrency issue like a transaction conflict. Server error: Often safe to retry with a short backoff.
11 400 OUT_OF_RANGE The operation was attempted past the valid range. Client error: Correct the range or index.
12 501 UNIMPLEMENTED The operation is not implemented or not supported by the API. Client error: Check API version and available features. Don't retry.
13 500 INTERNAL An internal error occurred. This is a general catch-all for server-side issues. Server error: Generally retryable with exponential backoff. If persistent, report the issue.
14 503 UNAVAILABLE The service is currently unavailable. This is most likely a transient condition. Server error: Highly recommended to retry with exponential backoff.
15 500 DATA_LOSS Unrecoverable data loss or corruption. Server error: Rare. Indicates a serious problem. Don't retry. If persistent, report the issue.
16 401 UNAUTHENTICATED The request does not have valid authentication credentials. Client error: Verify your authentication tokens and credentials. Don't retry without fixing authentication.

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:

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.

Previous
Error types
Next
Common errors