Custom Response Codes

Note: Custom Response Codes are not supported on the Essential platform.

Custom response codes allow you to specify which HTTP status code is returned by Signal Sciences when a request is blocked. By default, Signal Sciences will return a 406 response code when a request is blocked. With custom response codes enabled on a rule, you can select an alternative response code to be returned instead of 406.

Custom response codes can facilitate additional actions at the edge depending on the rule triggered. For example, a specific custom response code can be used to tell your CDN to redirect the request to a CAPTCHA. The Fastly CDN supports custom response codes in VCL to redirect requests to other pages, such as custom error pages.

Limitations

Custom response codes can only be set on individual rules that block requests.
Each site may have up to 5 unique response codes across all rules at any time.
There is no limit to the total number of rules that use custom response codes.
Custom response codes require a minimum agent and module version.
Custom response codes are limited to numbers between 400 and 599.

Note: If an unsupported module version is told to block a request due to a rule that uses a custom response code, that request will not be blocked.

What happens when a rule with the default response code and a rule with a custom response code both block a request?

The request is blocked and the custom response code is returned.

What happens when two rules with different custom response codes both block a request?

The request is blocked and the oldest custom response code is returned, based on when the response codes were first created.

For example, if Rule A had a custom response code created one week ago and Rule B had a custom response code created yesterday, the custom response code of Rule A would be used because that response code was created earlier.

Considerations when using certain response codes

This feature allows Signal Sciences to return response codes between 400-599 to upstream systems. Take care to ensure you understand the behavior of the upstream system before choosing one of these codes. Considerations include:

Some CDNs may automatically cache certain response codes. For example, the Fastly CDN automatically caches 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.

How to set a custom response code

When creating or editing a rule:

From the Action type menu, select Block.
Beneath the Action type menu, click Change response. The Response code (optional) field appears.
In the Response code (optional) field, enter the custom response code to return when the rule blocks a request. You can only use codes between 400 and 599.
Click Create site rule or Update site rule at the bottom of the rule editor.

Minimum version support

The following agent and module versions support custom response codes:

Name	Minimum version
Agent	4.10+
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+