Skip to main content
Omnitracs Knowledge Base

Web Service Exceptions

Overview

Exception handling within web services can be a very complicated task, depending on the platform you are using. Some platforms hide the internal implementation of web services. .NET is such an example. Many of the lower-level errors are trapped in the .NET framework and handled gracefully. Other platforms which reveal the actual implementation also reveal lower-level errors more plainly.

So as not to gloss over any of the lower-level details, we will discuss the full range of errors and exceptions below.

 

Protocol Errors

Fundamentally, web services are not much more than sockets conveying specific information. A web service request and response involves these parts:

  1. Client opens a socket to the server
  2. Client formats an XML document
  3. Client sends the XML content over the socket
  4. Server receives the XML content over the socket
  5. Server parses the content
  6. Server formats XML response content
  7. Server sends the response XML content over the socket
  8. Client receives the XML response content over the socket
  9. Client parses the XML response content

Since the basis of this involves sockets, a wide range of socket errors can occur, all of which prevent successful web service use, all of which must be handled by client programmers.

Examples of these kinds of errors include, but are not limited to:

  • Wrong URL endpoint
  • SSL errors
  • Wrong host name
  • Wrong port number
  • Certificate errors
  • Socket timeout
  • Socket creation failure

Your specific platform will dictate how these errors are revealed to the client application, and dictates somewhat how they are to be handled. In some cases, the error is revealed as a return code from a socket function. In other cases the error is revealed through the response buffer, which may or may not contain XML! As a client programmer you are responsible for identifying your particular platform's behavior.

 

Web Service Engine Errors

 

To review, web services are not much more than sockets conveying specific information. A web service request and response involves these parts:

  1. Client opens a socket to the server
  2. Client formats an XML document
  3. Client sends the XML content over the socket
  4. Server recieves the XML content over the sockedt
  5. Server parses the content
  6. Server formats XML response content
  7. Server sends the response XML content over the socket
  8. Client recieves the XML response content over the socket
  9. Client parses the XML response content

Platform-specific code on both the client and server sides must both format and parse the XML requests and responses. XML construction and parsing is itself a very detailed operation involving the potential for may problems. The server side adds additional "web service engine" complexity in order to determine which application must be invoked to handle each web service request.

Given this, a wide range of XML parser and web service engine errors can occur. These include, but are not limited to:

  • XML is not formatted properly
  • Missing required XML content
  • XML buffer overflow
  • Requested web service not defined

Most of the time, the error is conveyed within the XML response itself. How your particular platform handles errors like this is dependent on the platform, and is the responsibility of the client programmer to understand the platform's behavior. An example of how the XML response will appear is shown below:

<soapenv:Body>
   <soapenv:Fault>
      <faultcode xmlns:p55="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">
         p55:FailedAuthentication
      </faultcode>
      <faultstring>
         <![CDATA[com.ibm.wsspi.wssecurity.SoapSecurityException: WSEC6521E: Login failed.
         The exception is: javax.security.auth.login.LoginException: WSEC6690E: Failed to
         check username [QUALCOMM@CUSTOMERU] and password in the UserRegsitry:
         UserRegistryProcessor.checkRegistry()=false]]>
      </faultstring>
      <detail encodingStyle=""/>
   </soapenv:Fault>
</soapenv:Body>

Note that errors such as the one above are generated within the web service engine on the server side, and do not involve the actual web service application at all. For example, had the above error been generated in result to a specific method, then the code for that method had not yet been invoked when the error was generated and returned!

 

Application Specific Errors

 

A very wide range of error conditions may arise from both socket issues as well as XML and web service engine issues. These are discussed in other topics in this section.

If no socket errors, XML errors, or web service engine errors arise, application-specific errors are also possible. An application-specific error assumes that the web service request was transmitted successfully over the socket, and has made it through the XML parser and the web service engine on the server side. The application code has received the web service request and begun to act on the request.

Application-specific errors are by far the most numerous, because they are solely dependent on the application programmer. Each individual web service may return any number of application-specific errors to the client.

As a generic example, consider a "Update Delivery" web service, which needs both the current delivery Id, and new information to update in order to process the request. Application-specific errors can vary widely, including:

  • Delivery Not Found
  • Missing Required Information to Update
  • Delivery has been Deleted.
  • You do not have permission to perform this action

 

Soap Faults

All MMS web services will return application-specific errors either via a "Soap Fault" mechanism, or directly in the response.

The soap fault will contain the faultcode and faultstring indicating what the error might have been.
The following is an example of an application-specific error which may arise during a call to the SendDelivery web service. If you look at the list of exceptions at the bottom of the SendDelivery page, you will see the exception below defined in the list.

<SOAP-ENV:Body>
  <SOAP-ENV:Fault>
    <faultcode>SOAP-ENV:Client</faultcode>
    <faultstring xml:lang="en">009: Group was not found.</faultstring>
  </SOAP-ENV:Fault>
</SOAP-ENV:Body>

Response Based Errors

A response may also contain errors with more details defining the error condition. See the Web Services documentation for the details.

<SOAP-ENV:Body>
  <ns1:createDeliveryResponse>
   <ns1:deliveryId>-1</ns1:deliveryId>
   <ns1:deliveryStatuses>
    <ns1:statusType>ERROR</ns1:statusType>
    <ns1:code>error.reason.request.sender.length</ns1:code>
    <ns1:reason>Sender allowed characters limit of 80</ns1:reason>
   </ns1:deliveryStatuses>
   <ns1:deliveryStatuses>
    <ns1:statusType>ERROR</ns1:statusType>
    <ns1:code>error.reason.request.vehicles.groups.bothempty</ns1:code>
    <ns1:reason>Both vehicleIds and group names cannot be empty</ns1:reason>
   </ns1:deliveryStatuses>
  </ns1:createDeliveryResponse>
 </SOAP-ENV:Body>

 

  • Was this article helpful?