Partial Failure

Some AdWords services allow you to request that valid operations be committed and failed ones return errors. This feature -- called partial failure -- allows you to handle the failed operations separately at the end.

Technical details

To utilize this feature, you’ll need to set this optional SOAP header:

<partialFailure>true</partialFailure>

The service will carry out the operations that had no errors. It will return results for successful operations and errors for failed ones. This header is ignored for non-mutate operations.

This feature is supported by the following services:

Usage

Assume that you need to add a set of keywords to your account. However, some of the keywords may have editorial policy violations. You want to submit the valid keywords, but have the failed keywords returned along with their errors.

Create the service

Start by enabling partialFailure mode as follows:

// Enable partial failure.
session.setPartialFailure(true);

Create the operations and make the API call

Create the mutate operations and make the API call as usual.

List<AdGroupCriterionOperation> operations = new ArrayList<AdGroupCriterionOperation>();

// Create keywords.
String[] keywords =
    new String[] {"mars cruise", "inv@lid cruise", "venus cruise", "b(a)d keyword cruise"};
for (String keywordText : keywords) {
  // Create keyword
  Keyword keyword = new Keyword();
  keyword.setText(keywordText);
  keyword.setMatchType(KeywordMatchType.BROAD);

  // Create biddable ad group criterion.
  BiddableAdGroupCriterion keywordBiddableAdGroupCriterion = new BiddableAdGroupCriterion();
  keywordBiddableAdGroupCriterion.setAdGroupId(adGroupId);
  keywordBiddableAdGroupCriterion.setCriterion(keyword);

  // Create operation.
  AdGroupCriterionOperation keywordAdGroupCriterionOperation =
      new AdGroupCriterionOperation();
  keywordAdGroupCriterionOperation.setOperand(keywordBiddableAdGroupCriterion);
  keywordAdGroupCriterionOperation.setOperator(Operator.ADD);
  operations.add(keywordAdGroupCriterionOperation);
}

// Add ad group criteria.
AdGroupCriterionReturnValue result =
    adGroupCriterionService.mutate(operations.toArray(new AdGroupCriterionOperation[] {}));

Handle the successful operations

Successful operations return result values by the service. Print them out if desired:

for (AdGroupCriterion adGroupCriterionResult : result.getValue()) {
  if (adGroupCriterionResult.getCriterion() != null) {
    System.out.printf("Ad group criterion with ad group ID %d, and criterion ID %d, "
        + "and keyword '%s' was added.%n", adGroupCriterionResult.getAdGroupId(),
        adGroupCriterionResult.getCriterion().getId(),
        ((Keyword) adGroupCriterionResult.getCriterion()).getText());
  }
}

Handle the failed operations

Failed operations return error information in the partialFailureErrors field. You can find the index of the failed operation by looking at the fieldPathElements property (available starting with v201702) or the fieldPath property (available in all versions) of the ApiError object in the partialFailures list.

for (ApiError apiError : result.getPartialFailureErrors()) {
  // Get the index of the failed operation from the error's field path elements.
  FieldPathElement[] fieldPathElements = apiError.getFieldPathElements();
  FieldPathElement firstFieldPathElement = null;
  if (fieldPathElements != null && fieldPathElements.length > 0) {
    firstFieldPathElement = fieldPathElements[0];
  }
  if (firstFieldPathElement != null
      && "operations".equals(firstFieldPathElement.getField())
      && firstFieldPathElement.getIndex() != null) {
    int operationIndex = firstFieldPathElement.getIndex();
    AdGroupCriterion adGroupCriterion = operations.get(operationIndex).getOperand();
    System.out.printf(
        "Ad group criterion with ad group ID %d and keyword '%s' "
            + "triggered a failure for the following reason: %s.%n",
        adGroupCriterion.getAdGroupId(),
        ((Keyword) adGroupCriterion.getCriterion()).getText(),
        apiError.getErrorString());
  } else {
    System.out.printf(
        "A failure has occurred for the following reason: %s%n", apiError.getErrorString());
  }
}

Code examples in other languages

The ErrorHandling folder of each client library contains the following code example that shows how to use this feature:

Send feedback about...

AdWords API
AdWords API
Need help? Visit our support page.