Was this page helpful?
Your feedback about this content is important. Let us know what you think.
Additional feedback?
1500 characters remaining
Handling Service Errors and Exceptions

Handling Service Errors and Exceptions

For details on error handling and troubleshooting your application, please see the sections below.

Partial Success using the Campaign Management Service

For most entities, partial success is supported when calling Campaign Management service operations. This means that when adding, updating, or deleting entities in batches of one or more, the operation may succeed for some and fail for part of the batch. For each list index where an entity was not added, the corresponding element will be null. The PartialErrors element represents an array of BatchError objects that contain details for any entities that were not successfully added, updated, or deleted. The list only includes a BatchError for unsuccessful attempts, and does not include null elements at the index of each successfully added entity. Similarly some operations return NestedPartialErrors as a list of BatchErrorCollection, or a two dimensional BatchError.

The following operations include PartialErrors in the response.

The following operations include NestedPartialErrors in the response.

Fault Model Overview

When an operation fails, it can return one of the following faults. To determine the fault exceptions that an operation can return, see the reference page for the operation.

  • AdApiFaultDetail

  • ApiBatchFault

  • ApiFault

  • ApiFaultDetail

  • EditorialApiFaultDetail

All fault objects are derived from the ApplicationFault object. The ApplicationFault object defines the TrackingId element, which uniquely identifies the log entry that contains the details of the API call.

The fault exceptions include one or more error objects. The error objects contain the details of why the service operation failed and a code that uniquely identifies the error. For a list of error codes, see Bing Ads API Error Codes.

Available fault and data objects vary per service. The following table describes the fault model and links to error data objects for each service.



Ad Insight

All ad insight operations may throw AdApiFaultDetail and ApiFaultDetail.

For more information, see Ad Insight Error Data Objects.


All bulk operations may throw AdApiFaultDetail and ApiFaultDetail.

For more information, see Bulk Error Data Objects.

Campaign Management

All campaign management operations may throw AdApiFaultDetail.

Some campaign management operations such as AddAdGroupCriterions, UpdateAdGroupCriterions, SetAdExtensionsAssociations, and UpdateAdExtensions throw either ApiFaultDetail or EditorialApiFaultDetail.

For more information, see Campaign Management Error Data Objects.

Customer Billing

System_CLiX_note Note

Version 10 is not yet available for the Customer Billing service. You can use Bing Ads API Version 9.

All customer billing operations may throw AdApiFaultDetail and ApiFault.

Some customer billing operations may also throw ApiBatchFault.

For more information, see Customer Billing Error Data Objects.

Customer Management

System_CLiX_note Note

Version 10 is not yet available for the Customer Management service. You can use Bing Ads API Version 9.

All customer management operations may throw AdApiFaultDetail and ApiFault.

For more information, see Customer Management Error Data Objects.


System_CLiX_note Note

Version 10 is not yet available for the Reporting service. You can use Bing Ads API Version 9.

All reporting operations may throw AdApiFaultDetail and ApiFaultDetail.

For more information, see Reporting Error Data Objects.

Common Errors

Runtime errors may be caught and handled. Documentation is available for potential error codes which may be observed. The following are some common errors that you may encounter.

Code 105

Typically indicates usage of an incorrect username, password, or developer token for the target environment. For example your credentials may be valid in production, and when targeting sandbox you would observe code 105.

Code 106

Typically indicates that while the credentials are correct for the target environment, the user does not have access to one of the entities specified in the request. For example, calling SubmitGenerateReport where the specified user does not have permissions to the specified account identifier.

HTTP 500

All Bing Ads services adhere to the Simple Object Access Protocol (SOAP) 1.1 specification whereby errors are returned with a HTTP 500 code. For example, see the following.

HTTP/1.1 500 Internal Server Error

This is not in and of itself representative of an actionable code, and you should inspect the fault details for more information on the specific error.

Troubleshooting Your Application

Typically when a call fails it is because the SOAP elements are invalid, out of order, or you specified the wrong credentials. To verify both cases, you should capture the request SOAP envelope. You can compare your capture to the corresponding SOAP example documented for each service operation. Fiddler is an optional tool for debugging and capturing SOAP envelopes when making web service calls. For details about downloading Fiddler, go to the Fiddler Web Debugging Proxy site.

Java Options

In Java you can follow these steps to capture the SOAP envelopes in Fiddler.

  1. Export the Fiddler certificate from the root certificate store. Click Tools > Fiddler Options. Select the HTTPS tab, and click the Export Root Certificate to Desktop button.

  2. Use the following command to import the certificate into the cacert store used by Java, for example execute from PowerShell as Administrator.

    c:\Program Files\Java\jre6\bin>keytool -importcert -v -alias "Fiddler cert" -trustcacerts -keystore "C:\Program Files\Java\jdk1.8.0_20\jre\lib\security\cacerts" -storepass changeit -file <DesktopPathGoesHere>\FiddlerRoot.cer
  3. Add the following lines to your Java application.

    System.setProperty("http.proxyHost", "");
    System.setProperty("http.proxyPort", "8888");
    System.setProperty("http.proxySet", "true");

Perl Options

In Perl you can use the SOAP::Lite statement to capture the SOAP envelopes.

use SOAP::Lite ( +trace => all, maptype => {} );

PHP Options

In PHP you can use the following methods to capture the SOAP envelopes.

print $proxy->GetService()->__getLastRequest()."\n";
print $proxy->GetService()->__getLastResponse()."\n";

Engaging Support

To get help with issues that you cannot resolve, consider posting in the API Developer forum where an active Bing Ads product team or member of the developer community will try and help. If you do not find timely information via the developer forum, or if the investigation involves sensitive account or personal details, please contact Bing Ads Support.

To resolve the issue efficiently, please provide support with the following information up front.

  • Reproduction Steps: Include all header and body elements of the SOAP request, except for the AuthenticationToken or Password header element.

    System_CLiX_note Note

    If you are managing user authentication with OAuth, and escalating an issue related to error code 105 or 106, please also include the user identifier corresponding to the Microsoft Account.

    To get the user identifier for the current user, call the GetUser service operation and leave the UserId element null. If GetUser returns error code 1001, then the Microsoft Account is not linked to any Bing Ads account. For more information about linking a Microsoft Account, see Managing User Authentication with OAuth.

  • Issue or Error: Include all elements of the SOAP response, and please also note the date and time when the error occurred.

  • Historical Performance: Indicate whether the same request had worked for you in the past.

  • Frequency: Indicate whether you can now reproduce the issue every time or intermittently.

  • Environment: Indicate whether the issue occurs in the production or sandbox environment.

WCF Exceptions using C#

Generic SOAP faults that are not specific to Bing Ads API may also be thrown, and should be caught by your application. For example, C# applications may throw Windows Communication Foundation (WCF) exceptions such as Exception, TimeoutException, and CommunicationException.

For information about exceptions that you should expect from WCF, see Expected Exceptions.

You should not call the Close method in the finally block to release the service object. The objection is that the Close method can throw exceptions. If Close throws an exception, you must call the Abort method to ensure that all resources are released; otherwise, you could be leaking resources on the server. The recommended practice is to call Close within the try block, and call Abort from the caught exceptions.

For the same reason, the use of the using statement is not recommended. For more information, see Avoiding Problems with the Using Statement.

Community Additions

© 2015 Microsoft