Custom response code

Use cases

Some requests should not reach your origin server. A unified block notice, a maintenance page, or a temporary redirect can all be served directly from the edge. Forwarding such requests to your origin adds latency and increases origin load. A custom response code rule lets ESA return a specified HTTP status code and response page at the edge, removing 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

A custom response code rule applies when you want to return a fixed response code and an optional page directly at the edge. If your requirement is different, 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

From the rule list, you can perform the following operations on an existing rule:

• 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 no longer takes 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 in the list. The first rule that matches the request returns the response, and no later rules are evaluated. Order your rules carefully.

• Valid status code values range from 200 to 599, which covers all valid 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 additions, edits, and deletions take effect on edge nodes in real time. No manual refresh is required.