We are developing a new web service and are looking into the "best practice" for returning errors in the soap response.

We were looking into creating a error response object which every response would contain as a property. This seems a little heavy however and are wondering if it is possible to use the SOAP header to carry this information? How do you normally deal with custom errors using SOAP?

Was it helpful?


SOAPFault is used to hold error and status information, and server returns 500 in the HTTP header for it to state it as fault.

see the specification from

You can design your own information token by either placing it into soap header or even within an element in your return result as long as you document it clearly for third party. However that is not the standard way to go for raising errors.


Soap already uses custom headers for error info, all you need to do is throw an exception on the server side, and exception is raised on the client side as a SoapException.

You can thrown SoapExceptions on the serverside if you want more control over the exception message/info.

Edit: For extra information along with the request, custom soap headers can be used. Here's an example article on CodeProject that used custom soap headers for authentication, but custom soap headers can be used for other purposes like sending extra info that is not necessarily an error condition (can be business logic info)

I've used similar techniques in the past for complex operations. Especially when you need (multiple?) error descriptions as well as as error code.

Soap headers are for out-of-band information, and should not be used for error messages. Furthermore, soap headers should not be used in soap responses because:

  • if mustUnderstand is missing or 0, the client can safely ignore them.
  • if mustUnderstand is 1, the client cannot signal it doesn't understand it (since it's a response).

And yes, I know some WS-* standards describe soap headers in the response...


Use soap faults for errors that are severe enough that there is no response object. Add a status token to the response for warnings and information messages.

Licensed under: CC-BY-SA with attribution
Not affiliated with StackOverflow