In an effort to continue to improve report download functionality in the AdWords API, we’ve made some changes in v201209 to improve error handling and debugging for developers. In a future release, we also plan to separate API downloads from UI downloads to make the downloaded reports easier to work with for developers.

In v201209 we’ve introduced a new XML format for report download errors. Currently, we return a text string with the error message embedded within it. For example, if you mispelled the field Date as Datee:

!!!2|||-1|||ReportDefinitionError.INVALID_FIELD_NAME_FOR_REPORT @ ; trigger:'Datee'???

In v201209, this error will be returned in this XML format (HTTP response codes will remain unchanged):

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<reportDownloadError>
<ApiError>
<type>ReportDefinitionError.INVALID_FIELD_NAME_FOR_REPORT</type>
<trigger>Datee</trigger>
<fieldPath/>
</ApiError>
</reportDownloadError>


The new error reporting format will make it easier to handle report download failures. If you’d like to preview these changes, you can pass this special HTTP header when downloading reports for versions prior to v201209:

apiMode: true

Support for this new XML error format will be added to client libraries for v201209. We’ve also published an XSD including this new report download error XML at:

https://adwords.google.com/api/adwords/reportdownload/vYYYYMM/reportDownloadError.xsd

For v201209, you can see it here. Some other things to keep in mind with these new changes:
  • Remember to make sure you provide the version in the report download URL. With the next major release (and when specifying this new HTTP header), version will be required when downloading reports.
  • AdHoc reports must be used - it will no longer be possible to download by reportDefinitionId.
If you have any questions about this new XML format or the AdWords API in general, please post on the forum. Follow our Google+ page for updates about the AdWords API.