Generic error handling

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

When the Generic Error filter is configured, API Gateway examines the incoming message and attempts to infer the type of message to be returned.

For example, for an incoming SOAP message, it sends an appropriate SOAP response (SOAP 1.1 or 1.2) using the SOAP fault processor. For an incoming JSON message, it sends an appropriate JSON response. If the inference process fails, API Gateway sends a SOAP message by default.

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 settings

Configure the following settings on the General tab:

Enter an appropriate name for this filter to display in a policy.

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

Configure the following options in the Generic Error Contents section:

Show detailed explanation of error:
Returns a detailed explanation of the generic error 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:
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:
Return the Java stack trace for the error to the client. This option should only be enabled under instructions from Axway Support.

Show current message attributes:
Return the message attributes present at the time the generic error was generated to the client. For example, for an incoming SOAP message, each message attribute forms the content of a <fault:attribute> element.

Caution   For security reasons, do not use Show filter execution path, Show stack trace, and Show current message attributes in a production environment.

Use Stylesheet:
Select this option to transform the error message returned by the Generic error filter by applying an XSLT stylesheet. Click the browse button next to the Stylesheet field. Select an existing stylesheet from the list, or right-click the Stylesheets node to add a new stylesheet.

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

Create customized generic errors

Use the following approaches to create customized generic errors:

Use the Generic Error filter

On the Advanced tab, you can customize the generation of a response message when the request cannot be inferred as a SOAP or JSON request.

Apply Response Rules: When this setting is selected, you can select one of the following rules:

  • Delegate to Policy: Select a policy to generate the response message. For example, the policy could use a JSON Error filter to generate a JSON response.
  • Response Content: Set the response body content and headers directly in the respective text areas. You can use the API Gateway selector syntax to evaluate and expand request details at runtime. The values specified on this tab are used in the outbound request to the URL.
    • Body: Enter the content of the incoming request message body (body headers and body content). Defaults to ${content.body}.

    For example, enter the Content-Type followed by a return, and then the required message payload:

    • Headers: Enter the HTTP headers associated with the incoming request message. Defaults to ${http.headers}.

Use the Set Message filter

You can also use the Set Message filter to 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 SOAP fault handling. You can use the same approach to generate customized generic errors.

Related Links