An Enterprise Service Bus is becoming a core component in today’s Service oriented architectures.
Whenever we integrate multiple applications, One common problem we run into is that, in case of an exception being thrown by a
service, the end client receives an “Internal BEA error “instead of the actual exception being
thrown by the service.
This paper tries to explain why this happens and provide a solution approach on how meaningful custom
messages can be presented to the end SOAP client.
The fundamental reason for this is because of the way, Oracle Service Bus populates its context variables
such as $body and $fault when an exception is risen. Details regarding context variables can be found at
but at a high level, when an exception is thrown by the backend service, the exception is put in the
$body variable and a predefined System message and error code is put in the $fault variable. The web
service client gets a SOAP fault which is populated by the content in $fault and that information is of no
help for any troubleshooting.
In order to provide custom error messages to the end client, we implemented the following approach –
1. Configure a Service Error Handler for the Proxy
2. Create two proxies – one a generic proxy to the business service and another client specific
proxy that calls the generic proxy
3. Leverage the Reply with Failure construct that populates $fault with $body
Details regarding the various error codes generated by the service bus can be found at
http://edocs.bea.com/alsb/docs30/javadoc/constant-values.html. The error codes that are most
Error Code Explanation
BEA-380001 Service up, but an application exception
BEA-38002 Service unavailable
Other ones Service up, but infrastructure related issue
With the above information on hand, in the Service Error Handler of the generic proxy, we used the
if-then –else , XQuery functions and raise Error constructs provided by the service bus to throw the
appropriate user friendly exception.
- $fault can be interrogated using ” fn:starts-with($fault/ctx:errorCode/text(),”BEA-380002″)
- $body can be interrogated for application error using fn:starts-with($body/soapenv:
Fault/detail/error/text(),”ServiceProcessor.getData(): Invalid Data Sent “)
- Raise Error using a custom error code with a custom error message
Thus, in a nutshell, Generic Proxy identifies if it is a System exception or Application exception
and rethrows a user friendly exception. The key point is that when a custom exception is
thrown from the Generic proxy, $body contains the user friendly message and $fault contains
the custom error code.
The client specific proxy, in its service error handler uses the if-then-else construct
- interrogates $body using fn:starts-with($body/soap-env:Fault/faultString,”BEA”). If it does, it
implies that this is a system error and it raises a user friendly system error
- Else, it replies with failure.
With reply on failure construct, Oracle Service Bus populates $fault with $body and thus enables the
web service client to see the actual error message from the SOAP Fault.
By implementing the approach presented above, readers can customize the error messages to their
end SOAP clients and hide the arcane Oracle Service Bus errors.
1. Oracle Service Bus User Guide –