Better Know an Error: RateExceededError

One of the ways that we ensure reliable access to the AdWords API system is to enforce a queries per second (QPS) limit. This limit is in place to prevent out-of-control or malicious software from overwhelming the API servers with requests and causing problems for other developers. A token bucket algorithm is used to meter the requests, allowing for both steady and burst traffic to the API. It’s not possible to recommend exact numbers on safe QPS levels, since the rate limit fluctuates based on several variables, including server load.

In the v13 version of the API, requests that were made in excess of the limit were queued on the API server until they could be run, resulting in what seemed like very long execution times for some requests. The new API doesn't process these requests and instead returns a SOAP fault containing a RateExceededError (formerly QuotaExceededError in v200909). We believe this is an important feedback mechanism that ensures that you are aware of the issue and can adjust your applications accordingly.

We recognize that you may sometimes exceed the limit and receive this error due to factors not fully in your control. It is important to note that there is no penalty for doing so and there is no effect on your allocated API units. The error is transient and is usually resolved automatically after 30 seconds of inactivity. Typically the error is tied to the AdWords account being accessed, not the developer token used to make the request, so applications that manage multiple client accounts can temporarily switch focus to another account and return later to the one which threw the error.

If you are running into these errors often, steps should be taken to reduce the rate at which your application makes requests to the API. One simple way to do this without sacrificing throughput is to increase the number of operations that are sent in each request. This allows you to get the same amount of work done in fewer requests, reducing your chances of exceeding the QPS limit.

Because of the reasons listed above you need to be sure that you catch this error in your applications and handle it appropriately. The RateExceededError object contains fields with metadata that can be used when handling the error.

• rateName - Contains the name of the rate that was exceeded. For the QPS limit, this value will read "Requests."


• rateScope - Contains the scope of the rate that was exceeded, which will be one of "ACCOUNT" for client account or "DEVELOPER" for developer token.


• retryAfterSeconds - Contains a suggested number of seconds your application should wait before retrying the request, typically 30.

As always, post any questions you have regarding this error or other aspects of the API to the forum.

Best,
- Eric Koleda, AdWords API Team

Reintroducing Video Ads

Back in 2007, we first introduced support for video ads (Click-to-Play Video) in the AdWords API. This required a dedicated VideoAd type, which made it less adaptive to future video formats. The AdWords API has significantly improved since then with more flexible support for handling various ad types.

Video ads in the API are now supported through a new type, the TemplateAd. Template ads allow for an easy way to introduce new ad types, defined through template ad formats, without having to add new ad types. In turn, this makes it possible to release new ad features and updates much faster without waiting for the next version of the API.

Before a video ad can be created, the campaign must be set to show ads on the content network. As in previous versions, the video itself must be uploaded to your account via the web interface (see instructions). Once your video is uploaded, it is assigned a media ID, one of the elements required to create a video ad, which can be retrieved through the MediaService’s get() method. Now you have everything you need to create a video ad via the AdGroupAdService using the Click-to-Play Video template ad format. The client libraries have examples for retrieving a media ID and creating video

ads in various languages. Here’s an example in Python,

operations = [
    {
        'operator': 'ADD',
        'operand': {
            'type': 'AdGroupAd',
            'adGroupId': ad_group_id,
            'ad': {
                'type': 'TemplateAd',
                'templateId': '9',
                'templateElements': [{
                    'uniqueName': 'adData',
                    'fields': [
                        {
                            'name': 'startImage',
                            'type': 'IMAGE',
                            'fieldMedia': {
                                'mediaTypeDb': 'IMAGE',
                                'name': 'Starting Image',
                                'data': image_data
                            }
                        },
                        {
                            'name': 'displayUrlColor',
                            'type': 'ENUM',
                            'fieldText': '#ffffff'
                        },
                        {
                            'name': 'video',
                            'type': 'VIDEO',
                            'fieldMedia': {
                                'mediaId': video_media_id,
                                'mediaTypeDb': 'VIDEO'
                            }
                        }
                    ]
                }],
                'dimensions': {
                    'width': '300',
                    'height': '250'
                },
                'name': 'VideoAdTemplateExample',
                'url': 'http://www.example.com',
                'displayUrl': 'www.example.com'
            }
        }
    }
]
ads = ad_group_ad_service.Mutate(operations)

As always, post any questions you have regarding this topic or other aspects of the API to the forum.

-- Stan Grinberg, AdWords API Team

Different ways to delete

Part of managing an AdWords account is cleaning out old or non-performing items, such as unused ad groups or low search volume keywords. Not all entities are deleted in the same way however, and the different methods are outlined below.

Use the SET operator and change the status to DELETED

This approach is used for entities that can be restored at any time and start serving again. The DELETED status is not permanent in this case and can be changed to ACTIVE in the future. For these requests you only need to include the entity's id and its new status.

This approach used by:

• CampaignService
• AdGroupService

Use the REMOVE operator

This approach is used for entities that are permanently deleted from your account and can't be restored. This operator doesn't guarantee that the entity is completely removed from your account and may remain but in a DELETED or DISABLED state.

This approach is used by:

• AdGroupAdService
• AdGroupCriterionService
• AdExtensionOverrideService
• AdParamService
• CampaignAdExtensionService

Use the SET operator and exclude the entity from the list

This method is used for entities that don't have unique ids but are returned in a list. This process involves retrieving the current list, removing the entity, and then sending back the updated list.

This approach is used by the CampaignTargetService.

As always, post any questions you have regarding this topic or other aspects of the API to the forum.

Best,
- Eric Koleda, AdWords API Team

AdWords Downtime: June 12, 10am-2pm PDT

We'll be performing routine system maintenance on Saturday, June 12 from approximately 10:00am to 2:00pm PDT. You won't be able to access AdWords or the API during this time frame, but your ads will continue to run as normal.

Best,

- Eric Koleda, AdWords API Team