Applies to QAComplete 12.21 SaaS, last modified on July 15, 2019

QAComplete SOAP API returns errors as SOAP faults. A SOAP fault response has HTTP status code 500 and contains an XML-formatted error message in the response body. Here is a sample SOAP fault:

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
   <soap:Body>
      <soap:Fault>
         <faultcode>soap:Client</faultcode>
         <faultstring>Error</faultstring>
         <faultactor>psWS.AuthenticationException</faultactor>
         <detail>
            <Description Text="Authentication data is not valid. Please retry ..."/>
         </detail>
      </soap:Fault>
   </soap:Body>
</soap:Envelope>

<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
   <soap:Body>
      <soap:Fault>
         <soap:Code>
            <soap:Value>soap:Sender</soap:Value>
         </soap:Code>
         <soap:Reason>
            <soap:Text xml:lang="en">Error</soap:Text>
         </soap:Reason>
         <soap:Node>psWS.AuthenticationException</soap:Node>
         <detail>
            <Description Text="Authentication data is not valid. Please retry ..."/>
         </detail>
      </soap:Fault>
   </soap:Body>
</soap:Envelope>

In code, you can catch SOAP faults and web service communication exceptions like this:

C#

using System.ServiceModel;
using System.ServiceModel.Channels;

...

try
{
  // Do something
}
catch (FaultException ex)
{
  MessageFault msgFault = ex.CreateMessageFault();
  string error = msgFault.HasDetail
                 ? msgFault.GetReaderAtDetailContents().GetAttribute("Text")
                 : ex.Reason.ToString();
  Console.WriteLine(error);
}
catch (CommunicationException ex)
{
  Console.WriteLine(ex.Message);
  Console.WriteLine(ex.InnerException);
}

Java

import javax.xml.ws.soap.SOAPFaultException;
import javax.xml.soap.SOAPFault;
import javax.xml.ws.WebServiceException;

...

try {
  // Do something
}
catch (SOAPFaultException e) {
  SOAPFault fault = e.getFault();
  String error = fault.hasDetail()
                 ? fault.getDetail().getAttribute("Text")
                 : fault.getFaultNode();
  System.err.println(error);
}
catch (WebServiceException e) {
  System.err.println(e.getMessage());
}

Known issue

For SOAP 1.2 users: in fault responses returned by the psWS service, the detail element does not have a namespace:

<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
   <soap:Body>
      <soap:Fault>
         ...
         <detail>
            <Description Text="Authentication data is not valid. Please retry ..."/>
         </detail>
      </soap:Fault>
   </soap:Body>
</soap:Envelope>

This is contrary to the SOAP 1.2 specification. This happens because the psWS service is based on the ASP .NET XML Web Service technology whose standard SOAPException class returns error information without specifying a namespace for the details element.

This means that SOAP 1.2 Java clients will not be able to obtain the details element for faults (that is, they will not be able to obtain error text). A workaround is to use a C# client, or use SOAP 1.1.

See Also

SOAP API Introduction

Highlight search results