| Standards for Technology in Automotive Retail |
| Home - News Feed

6.2. SOAP Faults
Prev | Chapter 6. Error Handling | Next

## 6.2. SOAP Faults

SOAP faults are used to indicate error situations that prevent the successful delivery of STAR contents for subsequent parsing and processing. While this specification does not prevent using SOAP faults to communicate business level errors generated by business rules, this specification RECOMMENDS that these types of errors be returned using the proper BOD type such as a ConfirmBOD or the corresponding Acknowledge BOD.

If you send a message that was not successful you may get back a response containing a SOAP fault element which gives you status information, error information, or both. A SOAP Fault is similar to an Exception object in common development platforms in that it conveys information about a problem that prevents further processing. Some STAR-specific SOAP fault codes have been defined for common faults. All STAR implementations must understand these faults and handle them accordingly. Standard SOAP faults should be preferred over custom fault codes, such as when WS-Security or the WS-I Basic Profile define specific faults to be used. Below is a list of common faults that have been defined by STAR. When used, the fault code must be prefixed by “STAR:” and appear as in STAR:Invalid Structure.

Note: When sending a SOAP Fault the HTTP Status code needs to be set to 500, according to the WS-I Basic Profile.

Table 6.1. STAR Standard Soap Faults

Fault Code | Description
--- | ---
Duplicate Document | This code refers to a document that already exists. This may happen for a BOD such as ProcessPartsOrder where the document identifiers to another existing parts order from the same dealer.
Not Authorized | This code occurs when the client attempts to perform an operation that is not authorized for the given action. This is not to be used for Authentication errors. Those should use the appropriate WS-Security SOAP Fault.
Server Error | An error (e.g. database server is down) on the server prevented the execution of the BOD. The client will have to resend the BOD at a later time.
BOD Not Supported | The received BOD or BOD version is not supported b the receiver.
Invalid Structure | The structure of the BOD is not valid. For example, the BOD failed schema validation.
Invalid BODID | A BODID was missing or is Invalid.
Time Exceeded | The processing time will exceed the real time transaction allowed time. Must resend with a Put for batch processing, and pull to receive the message.

A SOAP Fault object contains the following elements:

- Fault code: Always required. The fault code must be a fully qualified name: it must contain a prefix followed by a local name. The SOAP specifications define a set of fault code local name values, which a developer can extend to cover other problems.

- Fault string: Always required. A human-readable explanation of the fault.

- Fault actor: Required if the SOAP Header object contains one or more actor attributes; optional if no actors are specified, meaning that the only actor is the ultimate destination. The fault actor, which is specified as a URI, identifies who caused the fault. For an explanation of what an actor is, see the actor attribute.

- Detail object: Optional element. The SOAP Fault object may contain a Detail object that gives details about the problem.

Below is an example of a SOAP message carrying a valid Fault element:

Example 6.1. Sample SOAP Fault

    <?xml version="1.0" encoding="utf-8"?>
    <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
       <soap:Header>
       </soap:Header>
       <soap:Body>
         <soap:Fault>
            <faultcode>soap:Server</faultcode>
            <faultstring>Database server not available.</faultstring>
            <faultactor>http://localhost/WebServices/STAR/STARTransport.asmx</faultactor>
         </soap:Fault>
       </soap:Body>
    </soap:Envelope>

SOAP 1.1 defines the following standard fault codes under the SOAP namespace ("http://schemas.xmlsoap.org/soap/envelope/"):

- Client: This code should be used when an error is found in the received message. The error could be anything from a corrupted message to a missing required element. This fault code indicates that the received message is the cause of the error and that the client is to blame.

- Server: This fault code indicates that a problem at the server prevented the processing of the message. The error could be anything from an overloaded server to a failing database.

These fault codes represent classes of errors rather than specific errors. SOAP 1.1 allows extending the fault codes using the period notation, however this practice is discouraged by the WS-I Basic Profile 1.1 to avoid the risk of potential name conflicts.

| STAR Level 1 Requirement
STAR1009: All STAR Web Services are REQUIRED to understand and handle the STAR Specific SOAP Faults. STAR1010: All STAR soap fault error codes are REQUIRED to be be prefixed with STAR: and the appropriate STAR error code. i.e. STAR:Invalid Structure. STAR1011: All STAR soap fault error codes are REQUIRED to appear in the standard SOAP:Fault block. STAR1012: SOAP Faults are for Critical Processing errors only. Informational or warning errors SHOULD NOT be sent as a SOAP Fault.

Note that some specifications mentioned in this document define their own SOAP faults. For example, WS-Security defines a set of fault codes to address security related errors. These fault codes are described in the WS-Security section and should be used when appropriate.

| STAR Level 1 Requirement
STAR1014: WS-Security errors must send the appropriate WS-Security SOAP Fault for the authorization being used.

### 6.2.1. Sample Error Cases

Below are examples of different error situations and valid responses that a service provider can reply with.

Error Case | Valid Response (ConfirmBOD or SOAP Fault)
Wrong ProcessMessage namespace | Fault: soap:Client
Wrong BOD namespace | Fault: soap:Client
Misspelled BOD root element | ConfirmBOD: BodNotSupported Fault: soap:Client
Invalid or missing <Task> element | Fault: soap:Client Fault: wsse:FailedAuthentication ConfirmBOD: BodNotSupported ConfirmBOD: FieldMissing ConfirmBOD: InvalidBod
Missing <ReferenceId> | Fault: soap:Client ConfirmBOD: FieldMissing
Missing <DealerNumber> | Fault: soap:Client Fault: wsse:FailedAuthentication ConfirmBOD: FieldMissing
Invalid dealer number | Fault: wsse:FailedAuthentication ConfirmBOD: InvalidValue
Missing <BODId> | Fault: soap:Client ConfirmBOD: FieldMissing
Message too old (wsse:Security\wsu:Timestamp\wsu:Expires has expired) | wsu:MessageExpired
Missing Application Area | Fault: soap:Client Fault: wsse:FailedAuthentication ConfirmBOD: InvalidBod
Missing Data Area | Fault: soap:Client ConfirmBOD: InvalidBod
Invalid User ID in wsse:Security header | wsse:FailedAuthentication
Wrong password in wsse:Security header | wsse:FailedAuthentication
Corrupted XML | HTTP/1.1 400 Bad Request (specified by WS-I Basic Profile)
Wrong SOAP Action HTTP header | soap:Client
Wrong SOAP Action in HTTP header and wsa:Action | soap:Client
Misspelled wsse:Security namespace | wsse:SecurityTokenUnavailable

Prev | Up | Next
Chapter 6. Error Handling | Home | 6.3. Application Level Errors