Using custom agent response codes
Custom agent response codes allow you to specify the HTTP status code that is returned when a request to your web application is blocked. By default, all block actions return the 406 custom agent response code. You can change this default behavior by:
- updating the default blocking response code for the site (also known as workspace). Blocking actions use this response code unless a different response code is specified in a rule.
- creating request rules that have a block action and that will return a specified response code.
- creating advanced rate limit rules that have a block action and that will return a specified response code.
Custom agent response codes can facilitate additional actions at the edge depending on the rule triggered. For example, a specific custom agent response code can be used to tell your CDN to redirect the request to a CAPTCHA. The Fastly CDN supports custom agent response codes in VCL to redirect requests to other pages (e.g., custom error pages).
Limitations
When working with custom agent response codes, keep the following things in mind:
- The Essential platform does not support custom agent response codes.
- Supported custom agent response codes are 301, 302, and 400-599.
- Each site (workspace) may have up to 5 unique response codes at any time.
- There is no limit to the total number of rules that use custom agent response codes.
- Custom agent response codes require a minimum agent and module version. When an unsupported module version is told to block a request due to a rule that uses a custom agent response code, that request will not be blocked.
Response code precedence
Blocking actions use the site's (workspace's) default blocking response code unless a different response code is specified in a rule. Examples of this rule are as follows:
- When a request is blocked due to a CVE, API, or ATO system signal, the WAF returns the default blocking response code.
- When a request is blocked due to a rule that specifies a custom agent response code, the WAF returns that response code.
When rules with different custom agent response codes block the same request, the custom agent response code created first takes precedence over other relevant custom agent response codes. For example, let's say that your site (workspace) has the following rules:
| Rule | Condition | Action | Date created |
|---|---|---|---|
| E | IP Address (Client) equals 192.0.2.0 | Block and respond with 500 | 2022-12-01 |
| D | IP Address (Client) equals 192.0.2.0 | Block and respond with 400 | 2022-10-01 |
| C | IP Address (Client) equals 192.0.2.0 | Block and respond with 404 | 2022-08-01 |
| B | Path equals /example/path | Block and respond with 400 | 2022-06-01 |
| A | Path equals /example/redirect | Block and respond with 301 | 2022-04-01 |
In this example, a client with an IP address of 192.0.2.0 makes a request to the /custom-limits page of your web application. As the request meets the conditions of rules C, D, and E, the request is blocked. While rule C was created before rules D and E, the 400 response code from rule D is returned because it is the oldest relevant response code. Specifically, the 400 response code was first added to rule B on June 1st and the 404 and 500 response codes were created on August 1st and December 1st respectively.
Selecting custom agent response codes
Because custom agent response codes can be returned to upstream systems, ensure you understand the behavior of your upstream systems. Specifically, keep the following things in mind when selecting a custom agent response code:
- Some CDNs automatically cache certain response codes. For example, the Fastly CDN automatically caches 301, 302, 404, and 410 responses.
- Using a 401 response code may result in a username and password prompt to the client browser.
- Using response codes such as 400 or 403 may result in an artificial increase of measured “bad request” or “forbidden” requests.
- Response codes in the 5xx range are generally associated with server connections or application errors.
Minimum version support
The following agent and module versions support custom agent response codes:
| Name | Minimum version |
|---|---|
| Agent | Any |
| Apache | 1.8.0+ |
| Cloud Foundry | Any |
| Envoy | Any |
| Golang | 1.8.0+ |
| HAProxy | 1.2.0+ |
| Heroku | Any |
| IBM Cloud | Any |
| IIS | 2.2.0+ |
| Java | 2.1.1+ |
| .Net | 1.6.0+ |
| .Net Core | 1.3.0+ |
| NGINX | 1.4.0+ |
| NGINX C Binary | 1.0.44+ |
| Node.js | 1.6.1+ |
Unsupported agents and modules handle requests that should be blocked by rules with custom agent response codes in the following ways:
| Agent | Module | Result |
|---|---|---|
| Supported | Supported | Blocked with custom agent response code |
| Supported | Unsupported | Not blocked |
| Unsupported | Supported | Blocked with default response code of 406 |
| Unsupported | Unsupported | Not blocked |
| Supported (Reverse Proxy) | N/A | Blocked with custom agent response code |
| Unsupported (Reverse Proxy) | N/A | Blocked with default response code of 406 |
Changing the site's (workspace's) blocking response code
By default, all blocking actions for your site (workspace) return the 406 custom agent response code. To change this default behavior, complete the following steps:
HINT: To override your site’s (workspace’s) default blocking behavior under specific conditions, create a request rule or an advanced rate limiting rule. The rule must have a block action and specify an alternative blocking response code.
- Next-Gen WAF control panel
- Fastly control panel
Log in to the Next-Gen WAF control panel.
- From the corp navigation bar, click the Corp Manage menu and then select Sites.
- Click the name of the site that you want to edit.
- Click the Agent Configurations tab.
- In the Blocking response code field, enter the default blocking response code for your site. All blocking actions will return this response code unless a different response code is specified in a rule. Supported response codes are 301, 302, and 400-599.
- (Optional) If you entered
301or302in the Blocking response code field then, in the Redirect URL field, enter the absolute or relative URL of the redirect location. - Click Update.
Using redirect custom agent response codes
With redirect custom agent response codes (i.e., 301 and 302), you can specify the absolute or relative URL of the redirect location.
The redirect URL can pass one instance of the {{REQUESTID}} variable (e.g., https://www.example.com/blocked/?reqid={{REQUESTID}}). When used, this variable is replaced with the ID of the relevant request before the client is sent to the redirect location.
You can also use the {{URL}} variable to maintain the existing path and query string (e.g., https://www.example.com{{URL}}). It's similar to req.url in VCL.
