We recommend requesting no more than 10 reports concurrently and to use one thread for each concurrent download. If for some reason the report download fails, we recommend you retry after a short wait. The length of the wait should increase with the number of times the request has been tried (known as Exponential Backoff). This backoff algorithm helps prevent making too many requests to the server in a short period of time.
You should check the specific reason the download failed and only retry if it was a transient error (such as exceeding the rate limit) instead of retrying if the report definition XML was invalid. The HTTP Status of the response provides useful information:
- HTTP Status 500 indicates there is a transient server side issue and the request can be retried after a delay. We retrying no more than 5 times for any given report.
- HTTP Status 400 indicates there was a problem with the request (or the report itself) and retrying will not help.
- HTTP Status 200 means the report download was successful.
Another benefit of downloading reports in this fashion is you get data more quickly than with legacy cross-client reports. As soon as a report download succeeds, you can start processing the data by putting it into a database or performing further logic on the results.
We hope this discussion of best practices will help you with writing report download code in the future. We’ve published a reference implementation showing how to do this in java here. If you have any questions about downloading reports, you can ask us on the forum.
Kevin Winter, AdWords API Team