CodeSnip: Handling SOAP Exceptions in Web Services
page 1 of 1
Published: 11 Nov 2005
Unedited - Community Contributed
In this snippet, Vishal demonstrates how to throw and handle exceptions in Web services.
by Vishal Patil
Average Rating: This article has not yet been rated.
Views (Total / Last 10 Days): 31948/ 25

[Download Sample Code]



A Web service provides functionality independent of the programming languages and the operating system; hence, it’s necessary for the Web services to throw exceptions in a platform-independent manner. To accomplish this, we need to raise SOAP exceptions from the Web service that are compliant with the SOAP specification.


The following are the advantages of SOAP exceptions.


  • They handle exceptions in a consistent manner.
  • They follow the SOAP specification.
  • Explicitly raising SOAP exceptions communicates more information, such as detailed information of the exception, Web Service method name, and responsibility.


Now that we have had a look at the importance of raising SOAP exceptions, let us look at how to raise exceptions from Web services.


Raising Exceptions from Web Services

To accomplish this, we should use the SoapException class as it abstracts the complexities of the SOAP fault creation process. The SoapException class consists of the following properties that need to be populated before throwing the exception to the consumers.


  • Message—the contents of the exception.
  • Code—an enumeration that specifies the type of fault code (e.g. ClientFaultCode, ServerFaultCode, etc.).
  • Actor—the URL of the Web service method where the exception has occurred.
  • Detail—the detail element can be used to communicate more information about the exception to the callers.


For the purposes of this example, we’ll create a Web service named WSException, selecting a C# ASP.NET Web Service as the project template. Once the project is created, add a service called WSException and add a method named GetException and the following lines of code to that class.


Listing 1

public enum FaultCode


  Client = 0,

  Server = 1




public void GetException()




    int i = 1;

    int j = 0;

    int z;


    //generates the exception

    z = i / j;


  catch (Exception ex)


    throw RaiseException("GetException", "WSSoapException", ex.Message,

                      "1000", ex.Source, FaultCode.Server);




//Creates the SoapException object with all the error details

public SoapException RaiseException(string uri, string webServiceNamespace,

                                string errorMessage,

                                string errorNumber,

                                string errorSource,

                                FaultCode code)


  XmlQualifiedName faultCodeLocation = null;

  //Identify the location of the FaultCode

  switch (code)


    case FaultCode.Client:

      faultCodeLocation = SoapException.ClientFaultCode;


    case FaultCode.Server:

      faultCodeLocation = SoapException.ServerFaultCode;



  XmlDocument xmlDoc = new XmlDocument();

  //Create the Detail node

  XmlNode rootNode = xmlDoc.CreateNode(XmlNodeType.Element,



  //Build specific details for the SoapException

  //Add first child of detail XML element.

  XmlNode errorNode = xmlDoc.CreateNode(XmlNodeType.Element, "Error",


  //Create and set the value for the ErrorNumber node

  XmlNode errorNumberNode =

    xmlDoc.CreateNode(XmlNodeType.Element, "ErrorNumber",


  errorNumberNode.InnerText = errorNumber;

  //Create and set the value for the ErrorMessage node

  XmlNode errorMessageNode = xmlDoc.CreateNode(XmlNodeType.Element,



  errorMessageNode.InnerText = errorMessage;

  //Create and set the value for the ErrorSource node

  XmlNode errorSourceNode =

    xmlDoc.CreateNode(XmlNodeType.Element, "ErrorSource",


  errorSourceNode.InnerText = errorSource;

  //Append the Error child element nodes to the root detail node.




  //Append the Detail node to the root node


  //Construct the exception

  SoapException soapEx = new SoapException(errorMessage,

                                           faultCodeLocation, uri,


  //Raise the exception  back to the caller

  return soapEx;




In the above listing, as the name suggests, the GetException Web method throws the exception (as we are dividing 1 by 0 to generate the exception) when it is called from the client side. This exception is converted into the SoapException object by the RaiseException method which is called in the catch block of the GetException Web method.


In the above code, the RaiseException method is used to raise exceptions from the Web service in the form of a SoapException object. The RaiseException method first looks at the FaultCode enum parameter value to find out the source of the exception. If an exception has occurred due to problems in the server side (for example, the file is not found), it sets the value of FaultCode to SoapException.ServerFaultCode.


Similarly, if an exception has occurred due to a problem in the input parameter passed by the client to the Web method, then FaultCode is set to SoapException.ClientFaultCode. Once it is done, it creates an XmlDocument object to hold the contents of the detail element. It adds all the child elements under the detail element and then passes the detail node to the constructor of the SoapException object. Finally, it returns the SoapException object back to the caller by using the return statement. Detail element inside the SoapException object will look as follows.


Listing 2


  <Error xmlns=" /">


    <ErrorMessage>Exception Message</ErrorMessage>

    <ErrorSource>Exception Source</ErrorSource>




When the client application receives a SoapException from the Web service, it looks at the Detail property of the SoapException object to get more information about the generated exception.


Handling Exceptions at the Client Side

This section provides an example to handle the exceptions raised from the Web service on the client side. To demonstrate this, let us create a new GUI project named SoapException. Once the project is created, add a command button to the default form and name it RaiseException. Add a Web Reference to the WSException project (see Listing 1). Then modify the Click event of the command button to look like the following.


Listing 3

public void RaiseException_Click(object sender,

  System.EventArgs e)




    WSException WSEx = new WSException();



  catch (SoapException soapEx)



    //Load the Detail element of the SoapException object

    XmlDocument doc = new XmlDocument();


    XmlNamespaceManager nsManager = new


    // Add the namespace to the NamespaceManager



    XmlNode Node =



    string errorNumber =



    string errorMessage =



    string errorSource =



    MessageBox.Show("Error Number is " + errorNumber);

    MessageBox.Show("Error Message is " + errorMessage);

    MessageBox.Show("Error Source is " + errorSource);



  catch (Exception ex)







In this article, we have demonstrated how to raise SOAP exceptions back to the client applications by using the SoapException object. We have also seen how the SoapException object allows us to communicate the exceptions using the SOAP fault code defined in the SOAP specification. Although the application we created was simple in functionality, it should provide a solid foundation for understanding how to raise and handle exceptions from a Web service.

User Comments

Title: ioioio   
Name: o8oi
Date: 2012-12-03 2:58:01 AM
Title: My error does not look as XML   
Name: Armando
Date: 2012-03-22 12:29:25 PM
Title: Very Helpful   
Name: Herries E
Date: 2010-09-23 5:59:29 AM
very helpful to return and extract the error from SoapException... great job!! Can't find from other resources...
Title: Thanks   
Name: Martin N
Date: 2010-02-13 12:38:54 AM
Thanks. Nice article !
Title: Thanks Much   
Name: Bradley Rigg
Date: 2009-02-25 3:37:27 PM
Just what I needed for MSFT web services. Would be nice if you covered non MSFT web services and what comes back when a SoapException happens.
Title: a   
Name: a
Date: 2008-07-18 12:23:15 AM
Excellent article. Thank u.
Title: Soap Exception in Web Services   
Name: Manjit Sarma(Bangalore)
Date: 2007-08-23 3:14:28 AM
Very helpful article.But I am getting in output of the webservice-'page cannot be displayed'.So I request your suggestion on how to proceed it.Anyways its a very Easy and Excellent article.

Title: Soap Exception in Web Services   
Name: sam
Date: 2007-04-13 9:30:51 AM
If an exception has occurred due to problems in the server side we are setting the value of FaultCode to SoapException.ServerFaultCode while calling RaiseException.What about exceptions on client side?
Do we need to handle such exceptions?
Title: soap exception in Webservice   
Name: Atul kumar
Date: 2007-01-09 2:34:08 AM
Good Job man

Title: SOAP Exceptions in Web Services   
Name: F. Basser (S. Africa)
Date: 2006-09-27 8:43:58 AM
I found this article, trimmed it down for my needs (I'm a lazy programmer) and it works like a charm. Before this I was really battling to pass error info back to the client.

Thanks very much!
Title: CodeSnip: Handling SOAP Exceptions in Web Services   
Name: Bob
Date: 2006-06-19 2:34:01 AM
The author used the same code originally written by Thiru Thangarathinam in Oct 7, 2003.
Title: CodeSnip: Handling SOAP Exceptions in Web Services   
Name: Greg
Date: 2006-06-01 10:51:37 PM
string feedback = "This is fantastic!";
Title: That is good stuff!   
Name: Alain Benoit
Date: 2006-03-16 1:58:13 PM
It helped me a lot! Easy to understand ! Thanks!
Title: Brilliant article   
Name: James Westfall
Date: 2006-03-03 9:41:32 AM
This works GREAT !
Title: GREAT Article   
Name: SDavis
Date: 2006-01-24 10:40:21 PM
GREAT Article! Actually explains in good terms wha the MS KB just throws in front of you
Title: Raising Exceptions from Web Services   
Name: Ch . Narayan --- (
Date: 2006-01-07 6:29:33 AM
I am searching 2 days for this type of article.
It is very easy to understand.
Finally this article is excellent.
Title: CodeSnip: Handling SOAP Exceptions in Web Services   
Name: R.Arul Benito
Date: 2006-01-06 6:17:36 AM
Excellent article

Community Advice: ASP | SQL | XML | Regular Expressions | Windows

©Copyright 1998-2024  |  Page Processed at 2024-06-25 10:14:05 AM  AspAlliance Recent Articles RSS Feed
About ASPAlliance | Newsgroups | Advertise | Authors | Email Lists | Feedback | Link To Us | Privacy | Search