SOAP Faults

When an error is raised during development, you will want to know where the error originated. Because this information is not useful to consumers of the Web service, you won't want to return meaningless line numbers when the service is deployed. Instead, you will want to provide other contextual information about what happened.

The SOAP Fault element has four separate pieces. In the following list, the bold names are for SOAP 1.1 and the SOAP 1.2 names are shown in italics.

• faultcode (Fault): Contains a value of VersionMismatch, MustUnderstand, Client, or Server.

• faultstring (Reason): Provides an explanation of why the fault occurred.

• faultactor (Role): Indicates the URI associated with the actor that caused the fault on the message path. In RPC‑style messaging, the actor should be the URI of the invoked Web service.

• detail (Detail): Carries information about why the error happened. This element can contain more XML elements or it could just be plain text.

The fault codes fall into the following categories.

• VersionMismatch: The SOAP receiver saw a namespace associated with the SOAP envelope that it does not recognize. When this fault code is received, the message should not be re‑sent. The SOAP namespace needs to be set to something the receiver does understand. JADE returns this code when the incoming namespace does not match the namespace of the Web service application.

• MustUnderstand: An immediate child of the SOAP header had MustUnderstand set to true. The receiver of the message did not understand the header. The receiver will need to be updated somehow (new code, new libraries, and so on) in order to make sense of the header. This fault code is currently not supported by JADE.

• Client (Sender): Something about the way that the message was formatted or the data it contained was wrong. The client needs to fix its mistake in order for the message to be sent back. When returning this fault code, you should also fill in the details element with some specifics on what needs to happen in order for the message to be processed. This fault code is returned by JADE if the service, method, or parameters are invalid.

• Server (Receiver): An error happened at the server. Depending on the nature of the error, you may be able to resend the exact same message to the server and see it processed. JADE returns this fault code if the method execution fails.

When a JADE exception is raised on the Web service provider, the fault is converted to a SOAP fault message and returned to the client. SOAP faults are returned as HTTP 500 errors.