What is the Static Response Handler?

The Static Response Handler allows you to return a custom HTTP response directly to the client without forwarding the request to your upstream server. This is useful for serving static content, custom error pages, maintenance notices, or implementing simple redirects without needing to modify your application code.

How Static Response Handler Works

When a rule with a Static Response Handler matches an incoming request, the request processing stops immediately, and a custom response is returned directly to the client. The response includes the status code, body content, and any headers you've specified. The request never reaches your origin server, which can reduce load and improve response times for simple content.

Configuration Options

The Static Response Handler supports these configuration options:

Option	Type	Required	Description
`status_code`	`integer`	Yes	The HTTP status code to return in the response (e.g., 200, 404, 503)
`body`	`string`	Yes	The content to return in the response body (HTML, JSON, text, etc.)

Note: To set the Content-Type header for your response, you'll need to use the Set Response Header handler in combination with the Static Response handler.

API Reference

When working with Rules through the API, Static Response handlers are represented in JSON format. This is the same structure used in the API endpoints for creating and updating rules.

{
  "type": "static_response",
  "status_code": 200,
  "body": "<!DOCTYPE html><html><body><h1>Hello World!</h1></body></html>"
}

In API requests, this handler would be included in the handlers array of a rule object:

{
  "name": "Maintenance Page Rule",
  "active": true,
  "matchers": [
    {
      "type": "path",
      "value": "/",
      "operator": "has_any_value"
    }
  ],
  "handlers": [
    {
      "type": "static_response",
      "status_code": 503,
      "body": "<!DOCTYPE html><html><body><h1>Site Under Maintenance</h1><p>We'll be back shortly.</p></body></html>"
    }
  ]
}

Configuration Examples

Example 1: Basic HTML Response

This handler will return a simple HTML page with a 200 OK status:

In the UI:

In the API:

{
  "type": "static_response",
  "status_code": 200,
  "body": "<!DOCTYPE html><html><body><h1>Welcome to Our Site</h1><p>This is a static page served via the rules engine.</p></body></html>"
}

Example 2: Custom 404 Error Page

This handler will return a branded 404 page:

In the UI:

In the API:

{
  "type": "static_response",
  "status_code": 404,
  "body": "<!DOCTYPE html><html><body><div class=\"error-container\"><h1>Page Not Found</h1><p>The page you're looking for doesn't exist. Please check the URL or navigate back to our <a href=\"/\">homepage</a>.</p></div></body></html>"
}

Example 3: JSON API Response

This handler will return a JSON response for an API endpoint:

In the UI:

In the API:

{
  "type": "static_response",
  "status_code": 200,
  "body": "{\"status\":\"success\",\"version\":\"1.0.0\",\"serverTime\":\"2023-01-01T12:00:00Z\"}"
}

Example 4: Temporary Redirect

This handler will return a 302 redirect:

Note: For redirects, you must use the Set Response Header handler in combination with the Static Response handler to set the Location header. The Set Response Header handler should come before the Static Response handler in your rule configuration.

In the UI:

In the API (complete rule with both handlers):

{
  "name": "Temporary Redirect Rule",
  "active": true,
  "matchers": [
    {
      "type": "path",
      "value": "/old-page",
      "operator": "is"
    }
  ],
  "handlers": [
    {
      "type": "set_response_header",
      "headers": [
        {
          "name": "Location",
          "value": "https://new-site.example.com"
        }
      ]
    },
    {
      "type": "static_response",
      "status_code": 302,
      "body": "anything"
    }
  ]
}

Common Use Cases

Here are some popular ways to use the Static Response Handler:

Maintenance Mode

Show a maintenance page when your site is being updated:

Create a rule without matchers to match all requests
Add a Static Response handler with a 503 status code and maintenance message
Disable the rule when maintenance is complete

Custom Error Pages

Serve branded error pages for 404, 500, or other error scenarios:

Create rules for specific error scenarios
Use Static Response handlers to return appropriate status codes with custom HTML

Feature Not Available

Block access to features that are temporarily unavailable:

Create a rule targeting specific features using a Path matcher
Use a Static Response handler to explain the situation to users

API Mocking

Create mock API endpoints for testing or development:

Create rules that match your API endpoints
Use Static Response handlers to return JSON data with appropriate status codes

Security Headers

Return security headers without content for OPTIONS requests:

Match OPTIONS requests using a Method matcher
Use a Static Response handler with a 204 status code and no body
Add security headers with the Set Response Header handler

Basic Bot Protection

Block basic bots and simple scrapers:

Create a rule with a Header matcher for empty User-Agent or User-Agent containing "bot"
Use a Static Response handler to return a 403 Forbidden status with a simple message
This helps reduce server load from unwanted crawlers and basic scraping attempts

Combining with Other Handlers

The Static Response handler is typically the final handler in a rule chain as it stops request processing and returns a response immediately. However, you can combine it with:

Set Response Header: Add custom headers to your static response
Delete Response Header: Remove default headers from your static response

Remember that when the Static Response handler executes, the request will not be forwarded to your upstream server, and no further handlers will be processed.

Best Practices

Keep static responses lightweight for optimal performance
Use proper HTML structure for HTML responses
Set appropriate content types for different response formats
Use appropriate HTTP status codes (200 for success, 400s for client errors, 500s for server errors)
For SEO considerations, use 301 redirects for permanent redirects and 302 for temporary ones
Validate your JSON responses to ensure they're properly formatted
Consider caching headers for static content that rarely changes

Troubleshooting

If your Static Response handler isn't working as expected:

Verify that your rule matchers are correctly identifying the requests
Check that you're using the appropriate status code for your use case
Ensure your HTML or JSON is properly formatted
If using with Set Response Header, confirm the headers are correctly defined
For redirects, verify that the Location header is properly set
Test your rule by checking the response in your browser's developer tools

Limitations

Maximum response body size: 1MB
Binary data is not supported in the response body
For large static assets, consider using a CDN or file hosting service instead

The Static Response handler provides a powerful way to serve content directly from your domain rules without hitting your backend servers. This can improve performance, reduce server load, and provide custom experiences for your users.

Until next time, keep building!

Need more help? Reach out via the Intercom chat widget and we'll be right with you!