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 site (also known as workspace) default blocking response code from 406 to an alternative response code. Blocking actions use the site (workspace) default blocking 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 will use the site (workspace) default blocking response code unless a different response code is specified in a rule. Examples of this rule are as follows:

• When a templated rule blocks a request, the site (workspace) default blocking response code is returned.
• When a rule with the site (workspace) default blocking response code and a rule with a custom agent response code both block a request, the custom agent response code is returned.

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:

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:

Unsupported agents and modules handle requests that should be blocked by rules with custom agent response codes in the following ways:

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.