JSON Error

Contents

Overview
General Configuration
JSON Error Contents
Customized JSON Errors

Overview

In cases where a JavaScript Object Notation (JSON) transaction fails, the API Gateway can use a JSON Error to convey error information to the client. By default, the API Gateway returns a very basic fault to the client when a message filter has failed. You can add the JSON Error filter to a policy to return more meaningful error information to the client. For example, the following message extract shows the format of a JSON Error raised when a JSON Schema Validation filter fails: 

{
	"reasons": [
	    {
	        "language": "en",
	        "message": "JSON Schema Validation filter failed"
	    }
	],
	"details": {
	    "msgId": "Id-f5aab7304f6c754804f70000",
	    "exception message": "JSON Schema Validation filter failed",
	   ...    
	}
}

[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 JSON Error filter, administrators have the flexibility to configure just how much information to return to clients, depending on their individual requirements.

For more details on JSON schema validation, see the topic on the JSON Schema Validation filter. For more details on JSON, see http://www.json.org/index.html.

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 JSON 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.

JSON 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 JSON Error is returned in the error message. This makes it possible to suppress the reason for the exception in a tightly locked down system. By default, the reason is displayed as message blocked in the JSON Error. This option displays the value of the ${circuit.failure.reason} message attribute selector.

Show filter execution path

When this option is selected, the JSON Error returned by the API Gateway contains the list of filters run on the message before the error occurred. For each filter listed in the JSON Error, the status is output (Pass or Fail). The following message extract shows a filter execution path returned in a JSON Error: 

"path" : {
      "policy" : "test_policy",
      "filters" : [ {
        "name" : "True Filter",
        "status" : "Pass"
      }, {
        "name" : "JSON Schema Validation",
        "status" : "Fail",
        "filterMessage" : "Filter failed"
      }, {
        "name" : "Generic Error",
        "status" : "Fail",
        "filterMessage" : "Filter failed"
      } ]
    },

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 when the JSON Error is generated are returned to the client. The value of each message attribute is output as shown in the following example: 

"attributes": [
	{
	    "name": "circuit.exception",
	    "value": "com.vordel.circuit.CircuitAbortException: JSON Schema Validation 
	    filter failed"
	},
	{
	    "name": "circuit.failure.reason",
	    "value": "JSON Schema Validation filter failed"
	},
	{
	    "name": "content.body",
	    "value": "com.vordel.mime.JSONBody@185afba1"
	},
	{
	    "name": "failure.reason",
	    "value": "JSON Schema Validation filter failed"
	},
	{
	    "name": "http.client",
	    "value": "com.vordel.dwe.http.ServerTransaction@7d3e1384"
	},
	{
	    "name": "http.headers",
	    "value": "com.vordel.mime.HeaderSet@76737f58"
	},
	{
	    "name": "http.response.info",
	    "value": "ERROR"
	},
	{
	    "name": "http.response.status",
	    "value": "500"
	},
	{
	    "name": "id",
	    "value": "Id-f5aab7304f6c754804f70000"
	},
	{
	    "name": "json.errors",
	    "value": "org.codehaus.jackson.JsonParseException: Unexpected character 
	    ('\"' (code 34)): was expecting comma to separate OBJECT entries\n at [Source: 
	    com.vordel.dwe.InputStream@592c34b; line: 3, column: 25]"
	},
	...
]

[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.

Customized JSON Errors

You can use the following approaches to create customized JSON errors:

Using the Generic Error Filter

Instead of using the JSON Error filter, you can use the Generic Error filter to transform the JSON error message returned by applying an XSLT stylesheet. The Generic Error filter examines the incoming message and infers the type of message to be returned (for example, JSON or SOAP). For more details, see the Generic Error topic.

Using the Set Message Filter

You can create customized JSON Errors using the Set Message filter with the JSON Error filter. 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 JSON 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 JSON Errors.

Prev  Up  Next
  Home