Custom response code

Use cases

Some requests should not reach your origin server. Block notices, maintenance pages, and temporary redirects can all be served directly from the edge. Forwarding such requests to your origin adds latency and increases load. Custom response code rules let ESA return the desired HTTP status code and response page at the edge, eliminating the round trip.

Typical scenarios include:

• Friendly error pages: Replace status codes such as 404 or 500 with a custom page that shows a user-friendly error message.

• Maintenance window: During scheduled maintenance, return a 503 status code with a maintenance page for specific paths.

• Block malicious requests: Match attack signatures and return a 403 status code with a notice page.

When to use custom response code rules

Use a custom response code rule to return a fixed response code and an optional page directly at the edge. For other requirements, use the appropriate ESA feature:

Prerequisites

Before you begin, ensure that you have:

• A domain name added to and served by ESA

• (Optional) A custom response page, if you plan to return page content along with the status code. Create the page first; you can then reference it from any rule.

Create a custom response code rule

1. In the ESA console, select Websites, and in the Website column, click the target site.

2. In the left navigation pane, choose Rules > Transform Rules.

3. On the Transform Rules page, select the Custom response code tab, and then click Add Rule.

4. In the Customize Response Code dialog, configure the following settings and then click OK:

   • Rule Name: A custom name for the rule, for example, my-rule.

   • Apply to: Define the matching conditions for the request. For example, Hostname equals www.example.com.

     Alternatively, edit the expression directly. For example, (http.host eq "www.example.com").

   • Custom Response Code:

     • Response Code: The HTTP status code to return. Valid values: 200 to 599.

     • Response Page: Select from your existing custom pages. The default is Unresponsive page, which returns only the status code without any page body.

Verify the rule

1. Send a request that matches the rule, by using curl -I https://<your-domain>/<matching-path> or a browser.

2. Confirm that the returned HTTP status code matches your configuration. If you configured a response page, the browser displays the corresponding custom page content.

Manage custom response code rules

You can perform the following operations on an existing rule from the rule list:

• Search: Enter a rule name in the search box at the top of the list to filter by name.

• Reorder: Drag a rule to change its position. Rules are matched from top to bottom in the list.

• Enable or disable: Toggle the rule status. A disabled rule does not take effect, but its configuration is preserved.

• Edit: Modify the rule name, matching conditions, response code, or response page.

• Delete: Remove a rule that is no longer needed. Deletion cannot be undone, so proceed with caution.

Usage notes

• Rules are evaluated from top to bottom. The first matching rule returns the response, and no subsequent rules are evaluated. Order your rules accordingly.

• Valid status codes range from 200 to 599, covering all standard HTTP status codes. Choose a code that fits your use case.

• Custom response code rules are independent of rewrite rules and security rules, and the three rule types take effect separately.

• Rule changes take effect on edge nodes in real time. No manual refresh is required.