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
