A fault is a fatal processing error in the service, such that valid data does not return by the normal output parameter process. In addition to the fault message, Pega Platform returns an HTTP Code 500 Internal Server Error.

You can also have the system return other, non-fatal activity status information to the client as the value of a response parameter set on the Response tab.

1. In the navigation pane of Dev Studio, click Records.
2. Expand the Integration-Services category, and then click Service SOAP.
3. In the list of Service SOAP instances, select the instance for which you want to configure fault messages.
4. Click the Faults tab.
5. On the Faults tab, in the Fault conditions section, in the Condition field, select the condition that causes the system to return the data that you specify:
   • To set the system to evaluate the when condition rule that you specify in the When key field, select When.

     If the condition evaluates to true, the system returns an exception with the specified data. If false, the system continues evaluating the next when condition rule in the list. If all specified when condition rules return as false, the system returns the response data specified on the Parameters tab of the When rule to the client application. Use this feature to extend the normal set of fatal error conditions that result in exceptions that are returned to the client.

   • To set the system to evaluate the when condition rule that you specify in the When key field, select Queue When. If the condition evaluates to true, the system queues the service request and returns a Pega Platform-specific SOAP fault that includes the queue item ID of the service request. To customize the fault reason string that is provided in the SOAP fault, select Constant from the Map from field, and then enter a string, such as Object was locked - queued for retry.(The queue item ID is provided in the SOAP fault detail string, so you do not need to explicitly include it in the mapping.) Note that if you configure a Queue When condition, you must specify a request processor in the Request processor field on the Service tab. For more information, see the Pega Community article Configure a service to queue a failed service request for another attempt.
   • To set the system to return an exception with the specified data if an error occurs while mapping incoming data from the request message to the clipboard, select Mapping Error. If the list of response conditions does not include an entry for mapping errors, the system returns a standard exception to the client application.
   • To set the system to return an exception with the specified data if an error occurs while authenticating the application client credentials, select Security Error. If the list of response conditions does not include an entry for security errors, the system returns a standard exception to the client application.
   • To set the system to return an exception with the specified data if a service error occurs, select Service Error. If the list of response conditions does not include an entry for service errors, the system returns a standard exception to the client application.
6. If the Condition field value is When or Queue When, in the When key field, specify the key of the when condition rule that you want to evaluate.
7. In the Map from field, specify the source of the SOAP fault reason value:
   The SOAP fault reason is also known as the SOAP faultstring in SOAP 1.1.
   • To map the SOAP header value from a property on the clipboard, select Clipboard.
   • To provide the literal value to send as the value of the SOAP header, select Constant.
8. In the Map from key field, specify the key of the property or rule from which to map the SOAP fault reason value.
   • If the Map from value is Clipboard, enter a reference to the text property to use as the source of the data that is being mapped.

     If you selected XML Literal as the data type, the property value must contain text that is formatted as well-formed XML.

   • If the Map from value is Constant, enter the literal value of the SOAP header.

     If you selected XML Literal as the data type, the property value must contain text that is formatted as well-formed XML.

9. If you intend to return a value for the SOAP fault detail element, in the Fault detail key field, enter the Stream Name (second key part) of the XML Stream rule.
   The system assumes that the XML Type key (second key part) of the XML Stream rule is the constant value MapFrom. The system uses the page class of this service rule as the first key part of the stream rule.
10. Click Save.