SOAP Fault Simulation

When simulating SOAP services, you can configure a response to return a SOAP Fault — the standard SOAP error mechanism. Use this to test how your application handles SOAP-level errors.

What it does

In the Edit Response window, a SOAP handler exposes a Return SOAP Fault option. When enabled, the response is serialized as a SOAP fault (HTTP 500) instead of a normal SOAP envelope (HTTP 200). You can set the fault code, message, actor, and a typed detail element.

When to use

Verify your client correctly detects soap:Fault and reads faultcode / faultstring.
Reproduce transient vs. permanent failures by switching between a fault and a success response.
Return a strongly-typed fault detail so your client can branch on the detail type.

How to use

In the Service Simulation view, open Manage Responses for a SOAP URL handler.
Select the Default tab or a named response tab.
In the SOAP panel, enable  Return SOAP Fault (the checkbox is labeled Activate).
Configure the fault:

Field	Description
Fault Code:	A `SoapFaultCode` value.
Fault Message:	The `faultstring` (e.g. `Internal error processing request`).
Fault Actor:	Optional actor URI.
Detail Type:	The fault detail element type. Choose from the service's `SoapFaultTypes`, or leave empty for no detail (`EmptyFaultDetail`).

Click Save Changes.

A SOAP fault always returns HTTP 500 Internal Server Error. When Return SOAP Fault is off, the response is a normal SOAP envelope and returns HTTP 200 OK.

SOAP Fault basics

A SOAP Fault is an XML element in the SOAP envelope body:

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <soap:Fault>
      <faultcode>soap:Server</faultcode>
      <faultstring>Internal error processing request</faultstring>
      <detail>
        <errorCode>ERR-5001</errorCode>
        <message>Database connection timeout</message>
      </detail>
    </soap:Fault>
  </soap:Body>
</soap:Envelope>

Common SOAP Fault Codes

Fault Code	Meaning	HTTP Status
`soap:VersionMismatch`	Invalid SOAP namespace or version	500
`soap:MustUnderstand`	Required header not understood	500
`soap:Client`	Request is malformed or invalid	500
`soap:Server`	Server-side error processing request	500

All SOAP faults return HTTP 500 regardless of the fault code.

Simulating fault scenarios

Transient fault, then success

Configure the operation's response with Return SOAP Fault enabled → assert the client receives soap:Fault.
Edit the response, disable Return SOAP Fault, and Save Changes → the next call returns the success envelope.

Fault based on request content

Use an XPath condition on the request body so the fault is returned only for specific input:

Condition: XPath //amount > 10000
Response: SOAP Fault (Return SOAP Fault enabled)

What it does​

When to use​

How to use​

SOAP Fault basics​

Common SOAP Fault Codes​

Simulating fault scenarios​

Transient fault, then success​

Fault based on request content​

See Also​