search close

Custom Response Codes

access_time Updated Jun 29, 2022

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 499.

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 arbitrary response codes between 400-499 to upstream systems, including common response codes such as 400, 401, 403, 404 and 410. 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.

How to set a custom response code

When creating or editing a rule:

  1. From the Action type menu, select Block.

  2. Beneath the Action type menu, click Change response. The Response code (optional) field appears.

  3. 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 499.

  4. 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+
PHP 2.0.0+
Python 1.3.0+

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.

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

Agent Module            Result
Supported Supported Blocked with custom 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 response code
Unsupported (Reverse Proxy) N/A Blocked with default response code of 406