Generic Error

Overview

In cases where a transaction fails, the API Gateway can use a Generic Error to convey error information to the client based on the message type (for example, SOAP or JSON). By default, the API Gateway returns a very basic error to the client when a message filter fails. You can add the Generic Error filter to a policy to return more meaningful error information to the client based on the message type.

When the Generic Error filter is configured, the API Gateway examines the incoming message and attempts to infer the type of message to be returned. For example, for an incoming SOAP message, the API Gateway sends an appropriate SOAP response (for example, SOAP 1.1 or 1.2) using the SOAP fault processor. For an incoming JSON message, the API Gateway sends an appropriate JSON response. If the inference process fails, the API Gateway sends a SOAP message by default. For example error messages, see the JSON Error and SOAP Fault topics.

You can also transform the error message returned by applying an XSLT stylesheet. The API Gateway implicitly transforms the incoming message into XML before applying the stylesheet to the message.

[Important] Important

For security reasons, it is good practice to return as little information as possible to the client. However, for diagnostic reasons, it is useful to return as much information to the client as possible. Using the Generic Error filter, administrators have the flexibility to configure just how much information to return to clients, depending on their individual requirements.

General Configuration

Configure the following general settings:

Name:

Enter an appropriate name for this filter.

HTTP Response Code Status

Enter the HTTP response code status for this Generic Error filter. This ensures that a meaningful response is sent to the client in the case of an error occurring in a configured policy. Defaults to 500 (Internal Server Error). For a complete list of status codes, see the HTTP Specification.

Generic Error Contents

The following configuration options are available in this section:

Show detailed explanation of error:

If this option is selected, a detailed explanation of the Generic Error is returned in the error message. This makes it possible to suppress the reason for the exception in a tightly locked down system (the reason is displayed as message blocked in the Generic Error). Defaults to the value of the ${circuit.failure.reason} message attribute selector.

Show filter execution path

When this option is selected, the API Gateway returns a Generic Error containing the list of filters run on the message before the error occurred. For each filter listed in the Generic Error, the status is given (pass or fail).

Show stack trace

If this option is selected, the API Gateway returns the Java stack trace for the error to the client. This option should only be enabled under instructions from the Oracle Support Team.

Show current message attributes

By selecting this option, the message attributes present at the time the Generic Error was generated are returned to the client. For example, for an incoming SOAP message, each message attribute forms the content of a <fault:attribute> element.

[Warning] Warning

For security reasons, Show filter execution path, Show stack trace, and Show current message attributes should not be used in a production environment.

Use Stylesheet

Select this option if you wish to transform the error message returned by applying an XSLT stylesheet. Click the browse button on the right of the Stylesheet text box, and select a stylesheet in the dialog. To add a stylesheet, right-click the Stylesheets node, and select Add Stylesheet. Alternatively, you can also add stylesheets under the Resources -> Stylesheets node in the Policy Studio main menu.

Because XSLT stylesheets accept XML as input, the API Gateway implicitly transforms the incoming message into XML. The API Gateway then retrieves the selected XSLT stylesheet and applies the transformation to the message, and sends the response in the format specified in the XSLT stylesheet.

Using the Set Message Filter

You can also use the Set Message filter create customized Generic Errors. The Set Message filter can change the contents of the message body to any arbitrary content. When an exception occurs in a policy, you can use this filter to customize the body of the Generic Error. For details on how to use the Set Message filter to generate customized faults and return them to the client, see the example in the SOAP Fault topic. You can use the same approach to generate customized Generic Errors.