In our previous blog post, we discussed how v2009 error handling works in synchronous APIs. In this blog post, we cover asynchronous error handling in BulkMutateJobService. If you are new to BulkMutateJobService, check out our introductory blog post and code.google.com article.
Due to its asynchronous nature, error handling in BulkMutateJobService is slightly different than in other services. Instead of throwing an ApiError object, BulkMutateJobService returns FailureResult or BatchFailureResult objects as its operation results. These objects in turn contain the relevant ApiErrors. BulkMutateJobService processes the operations within an operation stream in multiple atomic batches. If there is even one faulty operation in a batch, it causes the other non-faulty operations in the batch to fail as well. When a batch of n operations fails, you will get one FailureResult and n - 1 BatchFailureResults as results for the failed batch of operations. The FailureResult object will always be first in the batch, and will contain one ApiException object. The ApiException contains all the errors for the entire batch of operations, just like for other services. This will be followed by n - 1 BatchFailureResults, which can be viewed as placeholders, one for each operation in the batch.
For instance, assume that you are trying to create the following 9 text ads in a single OperationStream. For the purposes of this example, assume that the system processes operations in batches of 3. The errors are highlighted in red.
| Index | Ad | Destination Url | Error |
| 0 | New York Budget Hotel Clean and close to subway. Students save 20%! www.example.com/NewYork | http://www.example.com/NewYork | |
| 1 | Book New York Hotel Deals Research your New York Stay. Deals up to 70% from example.com. www.example.com/NewYork | http://www.example.com/NewYork | |
| 2 | Hotels In New York Book your hotel room online at a lower price via example.com!! www.example.com/NewYork | http://www.example.com/NewYork | Excessive punctuation in description2 |
| 3 | Manhattan Best Hotel Experience the Best of Manhattan For Rates As Low As $239/Night. www.example.com/NewYork | www.example.com/NewYork | Missing schema in destination url. |
| 4 | New York City Hotels Discount Discounted Rooms in New York City. Get Lowest Rates Available Today. www.example.com/NewYork | http://www.example.com/NewYork | |
| 5 | New York City Hotels Stay Smart in New York NY. Free internet & breakfast bar. www.example.com/NewYork | http://www.example.com/NewYork | |
| 6 | 70% Off New York Hostels Why Pay More? From $10 We Guarantee Lowest Prices - From 1 Night www.example.com/NewYork | http://www.example.com/NewYork | |
| 7 | Stylish New Hotel in NYC Enjoy Four-Star Amenities & Service Chelsea/Fashion District. Book Now! www.example.com/NewYork | http://www.example.com/NewYork | |
| 8 | Budget Lodging in NYC Comfortable, Clean Modern Economy Hotel.Great Downtown Location! www.example.com/NewYork | http://www.example.com/NewYork |
When BulkMutateJobService processes these operations, it will return the following results:
Result[0]: FailureResult.
ApiException.errors has one ApiError
PolicyViolationError @ operations[2].operand.ad.description2
Result[1]: BatchFailureResult, operationIndexInBatch = 1
Result[2]: BatchFailureResult, operationIndexInBatch = 2
Result[3]: FailureResult.
ApiException.errors have 1 ApiError
AdError.URL_NO_SCHEME @ operations[0].operand.ad.url
Result[4]: BatchFailureResult, operationIndexInBatch = 1
Result[5]: BatchFailureResult, operationIndexInBatch = 2
Result[6]: ReturnValueResult, successfully created Ad.
Result[7]: ReturnValueResult, successfully created Ad.
Result[8]: ReturnValueResult, successfully created Ad.
As shown in the results above, there is a 1:1 correspondence between the number of operations and number of results. You can get the successful operations by scanning the return value for results which are not FailureResult or BatchFailureResult (operations 6, 7 and 8 in this case). Then, scan through the results to locate FailureResult objects (which always appear at the beginning of the failed batch) to get the operation that actually failed (operations 2 and 3 in this case). You can now pick the failed operations that do not correspond to the ones obtained from FailureResult, and make a new job for them (0, 1, 4, 5). Note that the OGNL path in FailureResult is relative to the batch and not the operationstream, so you have to offset it by the index of FailureResult to get the failed operation (e.g. Results[3] is a FailureResult and its OGNL path is operations[0].operand.ad.url, so the failing operator in the original list is 3 + 0 = operations[3]).
A BulkMutateJob may also return the following error results, even though they're not common:
LostResult: This happens when BMJS has lost results for some of a job's operations. You can recover from this error by checking numFailedOperations and numUnprocessedOperations for the job. If both are zero, or if the number of errors in ApiError matches numFailedOperations, then the operations were successful, but the results are missing. In any other case, you have to retrieve the entities that were targeted by the operations and see if the operation actually succeeded or not.
UnprocessedResult: This indicates that the mutate operation was not processed. This could happen because the workflow implementation prevented the operation from being processed (e.g. the operations exceed API quota). You can recover from this issue by checking the job status, making sure that you have sufficient API quota left, and simply retrying the operations in a new job.
In an upcoming blog post, we will cover the most common errors you may get in v2009, and how to address them. We've included support for error handling in all of our client libraries to help get you started, so please try it out and share your feedback with us on the forum or the projects' issue trackers.
-- Anash P. Oommen, AdWords API Team
