However, the default response generated by Imperva may not be appropriate for a couple of different reasons:

1. By default, Imperva expects clients to be communicating using HTML  and sends error messages formatted in HTML as well.  If an API client is expecting JSON-formatted responses, then it will be incapable of parsing the error message sent by Imperva.
2. Another reason why error responses may need rewriting is that an API’s schema may define a special error response format.  If this is the case, it is unlikely that the default Imperva response matches this format.  As a result, even if the response is JSON-formatted, it may not be possible for the client to interpret it properly.

In these two cases, the default error messages generated by Imperva will cause issues with an API client.  This is why the ability to create error messages is useful for API developers.

Creating a Custom Error Response in Imperva

Custom error responses in Imperva take advantage of the ability to enforce API schema definitions.  For more information about how to load and enforce an API schema in Imperva, check out this video.

Configuration Settings

By default, Imperva is going to assume that requests to a webpage are going to be performed using HTML.  As a result, when an error occurs - such as violating the API schema - Imperva will send back an HTML-formatted error page.

While this is the default, it is not the only option.  Imperva is capable of returning responses based upon the content type of a request; however, this requires changing a setting within the Imperva dashboard.

With a particular website’s page, select the Settings option on the menu on the left-side of the screen.  Inside of this page, select General, then scroll to the bottom of the Page.

Near the bottom of the page, you should see a category of settings labeled “Miscellaneous” as shown above.  Under this category, click the Enable content base error response checkbox if it is not already checked.

The effect of selecting this option is to enable Imperva to send different error messages based upon the type of content that a client is expecting.  This is keyed off of the Accept header within a request.  Clients expecting to interact with an API should have this set to application/json, and Imperva can use this to send an error message in the format that the client software expects.

Creating a Correctly-Formatted Error Message

After configuring Imperva to generate JSON messages based upon the Accept header within a request, it should provide a JSON response.  However, this response may not be appropriate for the API client in question.

For example, see the sample API response generated by Imperva in response to an invalid access request.  This response includes a success code of False, an error code of 401, and an error message informing the user that a valid token is needed to access the API, all encapsulated within a “status” object.

While this may be appropriate in some cases, it may not match the message format defined within an API’s schema.  As a result, an API client configured to obey this schema will not know how to handle such a response.

This problem can be handled by creating a custom Rule Filter in Imperva that rewrites the response to the application.  For an introduction to writing Rule Filters in Imperva, check out this webinar.

The image above shows a Rule Filter designed to modify the error message sent from an application.  Note that the actual Rule Filter (at the top of the rule creation screen) is not defined.  This means that this rule will match any request to an application.

Lower, we see the Rule Action.  This action is set to Rewrite Response Error, meaning that, if an error occurs, this rule will edit the response before it reaches the client.  This response is further defined to cover Access Denied Errors, which broadly applies to blocking related events, such as an API Specification Violation.   Finally, we give this request an HTTP status code of a 400 (Bad Request), which matches the expected behavior of the API definition.

Below the sections defining the matching criteria, we see the section shown above.  This enables a custom error response to be defined for a given error.  In this example, the response is formatted as JSON using the radio buttons, and the text field contains the response to be sent.  Using this, it is possible to define a custom error response that meets the API schema’s specifications and provides the exact information needed by the client if such an error occurs.

Sending Appropriate Error Responses in Imperva

Imperva enables an API to strictly enforce its schema by blocking any request that violates the contract outlined in the schema.  However, it is also important that the API itself follows the schema as well.

While this article covers Access denied events, it is possible for the Imperva Cloud WAF to return error messages for other event types as well, such as Connection Timeouts.  It is important to also update those error messages to minimize the impact to API clients as the default error messages generated by Imperva may not be what an application is expecting based upon the schema for an associated API.  By defining custom error responses, it is possible to provide an API client with the information that it needs in the format that it expects.

Learn More with Imperva Community 

The Imperva Community is a great place to learn more about how to use Imperva cyber security technologies like API Security,  Cloud WAF,  Advanced Bot Protection, DDoS Protection, and more to establish efficient, secure processes for enterprise networks. Rely on the expertise of Imperva partners, customers and technical experts. 

Related Content: 
Enforcing API Schema Specifications in Imperva