Standards for Technology in Automotive Retail
Table of Contents
It is important to use HTTP errors, SOAP Faults, or BOD level errors consistently. However, this section acknowledges implementations may use different error mechanisms for the same types of errors. This section defines general guidelines between these error mechanisms and also refers to the appropriate STAR documentation with regard to BOD level error handling.
Across STAR transports, the mechanism of error reporting should be as consistent as possible.
To align with the above principle, communicate as many errors as possible within BODs and minimize the amount of errors communicated in a transport specific way (such as SOAP Faults).
Other principles specific to BOD level errors are detailed in the STAR Confirm BOD Implementation Guidelines.
Implementations MUST NOT communicate errors using mechanisms other than those defined by STAR documents, or use error codes not defined or approved by STAR.
The types of errors which can occur when a Web service client attempts to communicate with a Web service can be thought of as a spectrum. At one end of the spectrum are the pure transport related errors and at the other end are the errors resulting from the business processing of the BOD. The mechanisms used to communicate these errors differ. 4.2.2-1 depicts an example specific to the use of Web services over HTTP. Other transport level protocols may have other exceptions. Although many types of errors are shown, this list is not intended to be all-inclusive.
The general guidelines with the approach shown here are the following:
HTTP exceptions are truly transport specific. SOAP Faults include the following types of errors:
True Web service transport specific errors (e.g., Invalid operation and server too busy)
SOAP Faults defined as part of a Web service standard like WS-Security implemented by this document (e.g., FailedAuthentication)
SOAP Faults due to manifest and payload inconsistencies
SOAP Faults due to business level errors that could not be returned in a BOD.
BOD level errors are preferred over the previous transport specific errors; therefore, if the application area of the BOD is obtainable and the error is not a transport error, BOD level error handling SHOULD be used. Refer to the STAR Confirm BOD Implementation Guidelines for details on BOD level errors.
HTTP Errors are those that occur at the transport layer when trying to call the web service and the web service client should handle them according to WSI basic profile 1.1.
Web service client should check for the HTTP return code 200 to ensure the transaction that was attempted went through ok. If the client receives any HTTP return code other than 200, it should be handled accordingly. Typical situations an HTTP error could occur are as follows:
Common STAR HTTP Error Codes:
|When the web server where the web service is being hosted is down or not available.||404|
|When the DNS server is unable to resolve the domain name in the Endpoint.||400 or 500|
|When the Endpoint of the web service is not available.||503|
|When the SSL Handshake Failure occurs between the Client and the Web Server.||500|
|When the Web Service does not recognize the request sent by the client.||502|
|When the HTTP Request time out occurs. (NOTE: This is not the same as the timeout error we see in the SoapFault.)||408|