Troubleshooting Common Errors

This page lists tips for handling and preventing the most frequently encountered errors returned by the AdWords API. The Error.REASON shorthand pairs the error type with the value returned in its reason field.

Common Errors

AdError

Reason: INVALID_INPUT
Summary: One of the fields in an ad contains invalid characters.
Common causes: Using special characters in URLs
Recommended handling tips: N/A
Prevention tips: Validate URLs in your application before making a request to the API.

Reason

LINE_TOO_WIDE

Summary

One of the lines in an ad was longer than the maximum allowed length. The length limits are documented in the AdWords help center.

Common causes

Not counting the length of the default text in an ad parameter towards the total length of the line
Incorrectly specifying empty default text in an ad parameter tag. Use {param1}, not {param1:}.

Recommended handling tips

N/A

Prevention tips

Validate the length of the line before making the request.

AdGroupAdError

Reason: CANNOT_OPERATE_ON_DELETED_ADGROUPAD
Summary: An operation attempted to update a deleted ad.
Common causes: Once an ad is deleted, it can no longer be updated (including changes to its status).
Recommended handling tips: N/A
Prevention tips: Ensure that your code does not attempt to update deleted ads.

AdGroupCriterionError

Reason

INVALID_KEYWORD_TEXT

Summary

The keyword text contains invalid characters. A list of valid characters is available on the AdWords help center.

Common causes

The keyword text contains invalid characters.

Recommended handling tips

N/A

Prevention tips

Use the validateOnly header to check ads and keywords for errors before attempting to add them to your ad group.
Validate the keyword text in your application before making a request to the API.

AdGroupServiceError

Reason: DUPLICATE_ADGROUP_NAME
Summary: An ad group is being added or renamed, but the name is already being used by another ad group.
Common causes: Creating a new ad group with the name of a deleted ad group
Recommended handling tips: Log the error and/or present an error message to the user, optionally suggesting a unique ad group name or showing the list of names in use.
Prevention tips: Rename the ad group as you delete it.

AuthenticationError

Reason: CUSTOMER_NOT_FOUND
Summary: No account found for the customer ID provided in the header.
Common causes: Trying to access an account that was just created with CreateAccountService before the account is established in the backend.
Recommended handling tips: Wait an initial five minutes, then retry every 30 seconds.
Prevention tips: Wait a few minutes after the account is created before issuing requests against it.

Reason

GOOGLE_ACCOUNT_COOKIE_INVALID

Summary

The authorization token (authToken) in the request header either is invalid or has expired.

Common causes

The authToken is more than two weeks old.
The password on the account was reset, invalidating the authToken.

Recommended handling tips

Request a new token from the ClientLogin service. If you are using a client library, consult the client library's documentation on how to regenerate the token.

Prevention tips

Cache your authorization tokens for no longer than two weeks.

Reason

NOT_ADS_USER

Summary

The login used to generate the authorization token (authToken) is not associated with any AdWords account.

Common causes

The login information provided corresponds to a Google account that does not have AdWords enabled.
The sandbox environment has been refreshed, removing any existing accounts.

Recommended handling tips

N/A

Prevention tips

After a sandbox refresh, ensure you make a request to CampaignService.get() to reinitialize your account.

AuthorizationError

Reason: UNABLE_TO_AUTHORIZE
Summary: There was an issue with completing authorization for a given user/account.
Common causes: Attempting to create an account via CreateAccountService.mutate under a non-MCC account.
Recommended handling tips: N/A
Prevention tips: Use ServicedAccountService to determine if the account is an MCC account. The field Account.canManageClients should be true.

Reason: USER_PERMISSION_DENIED
Summary: There is no link between the MCC account authenticated in the request and the client account specified in the headers.
Common causes: The MCC link between the manager and client account was removed.
Recommended handling tips: N/A
Prevention tips: Use ServicedAccountService to determine which client accounts are linked to your MCC account.

BiddingError

Reason: BID_TOO_HIGH_FOR_DAILY_BUDGET
Summary: The bid on a keyword or ad group is higher than the daily budget of the campaign.
Common causes: N/A
Recommended handling tips: N/A
Prevention tips: Use CampaignService to get the budget of the campaign, then validate ad group or keyword bids against the budget before performing the request.

Reason: BID_TOO_MANY_FRACTIONAL_DIGITS
Summary: The bid value is not an exact multiple of the minimum CPC. For example, US$0.015 is not a valid bid.
Common causes: N/A
Recommended handling tips: N/A
Prevention tips: Verify that bids are multiples of the minimum CPC bid for the currency in use.

Reason: CANNOT_SET_SITE_MAX_CPC
Summary: The siteMaxCpc field can not be set to a non-zero value.
Common causes: The managed placements bid feature was sunset on March 15th, 2011.
Recommended handling tips: N/A
Prevention tips: Use the keywordContentMaxCpc field to set the bid across the entire Display Network.

BulkMutateJobError

Reason: PAYLOAD_STORE_UNAVAILABLE
Summary: The results of a bulk mutate job cannot be found or are temporarily unavailable.
Common causes: N/A
Recommended handling tips: Retry the request every few minutes, for up to an hour. After an hour any missing results will be replaced with a LostResult object.
Prevention tips: N/A

CampaignError

Reason: DUPLICATE_CAMPAIGN_NAME
Summary: A campaign is being added or renamed, but the name is already being used by another campaign.
Common causes: Creating a new campaign with the name of a deleted campaign
Recommended handling tips: Log the error and/or present an error message to the user, optionally suggesting a unique campaign name or showing the list of names in use.
Prevention tips: Rename the campaign as you delete it.

CustomerSyncError

Reason: TOO_MANY_CHANGES
Summary: There were too many changed entities to return.
Common causes: Specifying too broad of a date range
Recommended handling tips: Narrow the date range and retry the request. If the error persists, assume everything has changed and use each campaign data services' get requests to retrieve the most recent campaign data.
Prevention tips: N/A

DatabaseError

Reason

CONCURRENT_MODIFICATION

Summary

Multiple processes are trying to update the same entity at the same time.

Common causes

In a multi-threaded environment, more than one thread is operating on the entity.
A user in the AdWords web interface is updating the entity at the same time.
An internal process on the AdWords API servers is updating an entity at the same time.

Recommended handling tips

Wait for about 30 seconds, then retry the request.

Prevention tips

If your client application is multi-threaded, ensure that threads do not operate on the same campaigns or ad groups.
Try not to process operations against the same ad group or campaign in quick succession.

DistinctError

Reason: DUPLICATE_ELEMENT
Summary: The request contains two parameters that are identical and redundant.
Common causes: N/A
Recommended handling tips: N/A
Prevention tips: Remove duplicates (operations, parameters, list elements) before making the request. Look for fields that have the DistinctElements constraint.

EntityNotFound

Reason

INVALID_ID

Summary

The ID of the entity you are operating on isn't valid.

Common causes

Referencing the ID of an entity from a different account
Referencing the ID of an entity that was removed

Recommended handling tips

Log the error and examine the trigger field to ensure that the ID is being specified correctly and belongs to the current account.

Prevention tips

N/A

InternalApiError

Reason

UNEXPECTED_INTERNAL_API_ERROR

Summary

Something unexpected happened while processing the request.

Common causes

Temporary resource related issues in the AdWords API server
The API isn't functioning correctly due to a bug

Recommended handling tips

Wait for about 30 seconds, then retry the request. If this error occurs frequently, post the details to the forum for further troubleshooting.

Prevention tips

N/A

JobError

Reason: TOO_LATE_TO_CANCEL_JOB
Summary: The bulk mutate job can no longer be cancelled.
Common causes: Using the REMOVE operator on a job that is not eligible to be cancelled.
Recommended handling tips: N/A
Prevention tips: Only cancel jobs that are in the PENDING state and don't have all of their parts uploaded yet.

NotEmptyError

Reason

EMPTY_LIST

Summary

A required list is empty.

Common causes

Passing in an empty list of operations to a mutate method
Not including any keywords in a RelatedToKeywordSearchParameter

Recommended handling tips

N/A

Prevention tips

N/A

NotWhitelistedError

Reason: CUSTOMER_ADS_API_REJECT
Summary: The account is temporarily in read-only mode.
Common causes: The AdWords system is performing a backend migration on the account.
Recommended handling tips: Wait for about 30 minutes, then retry the request.
Prevention tips: N/A

OperationAccessDenied

Reason: ADD_OPERATION_NOT_PERMITTED
Summary: The ADD operator can't be used for operations in the service and target account.
Common causes: Attempting to add a campaign to an MCC account.
Recommended handling tips: N/A
Prevention tips: When authenticating as an MCC account, ensure that the clientCustomerId header refers to an AdWords account.

Reason: MUTATE_ACTION_NOT_PERMITTED_FOR_CLIENT
Summary: The attempted operation cannot be performed through the API.
Common causes: Attempting to modify a campaign that was created using the Google Boost Ads program.
Recommended handling tips: Flag the campaign in your system as being read-only.
Prevention tips: N/A

PolicyViolationError, CriterionPolicyError

Reason

N/A

Summary

An ad or keyword you are adding violates an AdWords policy.

Common causes

Your ad or keyword contains trademarks or medical terms.

Recommended handling tips

If the returned isExemptable field is true, then you can request an exemption for your ad or keyword. To request an exemption:

Create an ExemptionRequest and populate its key field with with the PolicyViolationKey returned with the error.
Add this ExemptionRequest to the operation that caused the error, then retry the operation.

Prevention tips

Use the validateOnly header to check ads and keywords for errors before attempting to add them.

QuotaCheckError

Reason: ACCOUNT_DELINQUENT
Summary: The MCC account that was used to register for API access does not have an active billing mechanism.
Common causes: The credit card used to pay for API charges has expired. Even developers that receive free API units must have an active billing mechanism at all times.
Recommended handling tips: Update the billing information in your account.
Prevention tips: N/A

Reason: ACCOUNT_INACCESSIBLE
Summary: The target account has been temporarily disabled due to suspicious activity and cannot be accessed via the API.
Common causes: N/A
Recommended handling tips: Contact your AdWords account representative for more information. If you don't have a representative or don't know who they are, use the contact form in the AdWords Help Center.
Prevention tips: N/A

Reason: INCOMPLETE_SIGNUP_LATEST_ADWORDS_API_TNC_NOT_AGREED
Summary: The AdWords API Terms and Conditions have not been agreed to.
Common causes: The MCC account that was used to register for API access does not have billing information entered.
Recommended handling tips: Enter billing information for the MCC account that was used to register for API access. Upon entering billing information, you will be shown the terms and conditions and given the choice to accept them.
Prevention tips: N/A

Reason: INCOMPLETE_SIGNUP_NO_BILLING_INFO
Summary: No billing method has been configured for the AdWords API.
Common causes: Billing information was not entered in the MCC account that was used to register for API access. Even tokens which receive free API units must have a valid form of billing configured in order to use the API.
Recommended handling tips: N/A
Prevention tips: Enter billing information for your MCC account after you apply for API access.

Reason: INCOMPLETE_SIGNUP_USER_INFO_PENDING
Summary: The developer token used in the request has not yet been reviewed.
Common causes: Developer token requests may take up to two weeks to be reviewed, although it's usually only a few days.
Recommended handling tips: N/A
Prevention tips: Wait until your developer token has been approved before making requests to the API. If it's been more than two weeks since you've submitted your developer token request then contact your account representative or AdWords Support.

Reason

INVALID_TOKEN_HEADER

Summary

The developer token in the request is missing or invalid.

Common causes

The developer token is not set on the request or it contains a typo.
A production developer token is used for a request to the sandbox.
The namespace of the headers in the request is not correct.

Recommended handling tips

N/A

Prevention tips

Ensure that a developer token has been set and matches the value in the AdWords API Center.
For requests to the sandbox, use the sandbox-specific developer token format.
Ensure that the headers of the request are in the namespace https://adwords.google.com/api/adwords/cm/{version}, where {version} is replaced with the version of the API being used.

RangeError

Reason: TOO_LOW
Summary: A value was lower than the minimum allowed.
Common causes: Forgetting to specify an ID, which results in a value of 0 being passed in.
Recommended handling tips: N/A
Prevention tips: Note any range limitations documented in the API reference.

RateExceededError

Reason: RATE_EXCEEDED
Summary: Too many requests were made to the API in a short period of time.
Common causes: Performing one request for every operation.
Recommended handling tips: Wait for about 30 seconds, then retry the request.
Prevention tips: Read the RateExceededError blog post for in-depth information about this error.

ReportDefinitionError

Reason

CUSTOMER_SERVING_TYPE_REPORT_MISMATCH

Summary

The type of report definition being created isn't compatible with the account type.

Common causes

Attempting to create a cross-client report in a regular (ad serving) AdWords account.
Attempting to create a single-client report in an MCC account.

Recommended handling tips

N/A

Prevention tips

Ensure that cross-client report definitions are only created in MCC accounts. The ServicedAccountService can be used to get account information, and if Account.canManageClients is true then the account is an MCC account.

RequestError

Reason: INVALID_INPUT
Summary: The request is malformed.
Common causes: Missing version string in the request URL to download reports.
Recommended handling tips: N/A
Prevention tips: Provide the version in the request URL. For example: https://adwords.google.com/api/adwords/reportdownload/v201109

RequiredError

Reason

REQUIRED

Summary

The request is missing required information.

Common causes

Missing ID when attempting to update an entity
Missing required fields when attempting to add an entity

Recommended handling tips

Log the error and/or present an error message to the user. The fieldPath attribute of the error indicates which field is missing.

Prevention tips

Read the API reference to find out which fields are required.

SizeLimitError

Reason: RESPONSE_SIZE_LIMIT_EXCEEDED
Summary: The response contains too many items.
Common causes: N/A
Recommended handling tips: N/A
Prevention tips: Use the paging functionality of the selector when fetching a large number of items.

AdWords API

Feedback on this document

Troubleshooting Common Errors

AdError

AdGroupAdError

AdGroupCriterionError

AdGroupServiceError

AuthenticationError

AuthorizationError

BiddingError

BulkMutateJobError

CampaignError

CustomerSyncError

DatabaseError

DistinctError

EntityNotFound

InternalApiError

JobError

NotEmptyError

NotWhitelistedError

OperationAccessDenied

PolicyViolationError, CriterionPolicyError

QuotaCheckError

RangeError

RateExceededError

ReportDefinitionError

RequestError

RequiredError

SizeLimitError

Authentication required

Signing you in...