Redirect Responder

The Redirect responder sends clients to a different URL using a 308 Permanent Redirect HTTP status code.

Overview

This responder is useful when you want to send blocked clients to an alternative location instead of showing an error or blocking them outright. The redirect uses HTTP 308, which preserves the request method and body.

Configuration

url

string

required

The destination URL to redirect clients to.This field is required when using the Redirect responder.Must be a valid URL (absolute or relative).

ranges

string[]

IP ranges to redirect. Can be CIDR notations or predefined service keys.Default: ["aws", "azurepubliccloud", "deepseek", "gcloud", "githubcopilot", "openai"]

whitelist

string[]

Optional list of specific IP addresses to exclude from redirection.Default: []

HTTP Response

status

number

308 Permanent Redirect

Location

string

The configured destination URL

Examples

localhost:8080 {
    defender redirect {
        ranges openai aws
        url "https://example.com"
    }
    respond "Content for humans"
}

Implementation Details

The Redirect responder is implemented in responders/redirect.go:14:

func (r *RedirectResponder) ServeHTTP(w http.ResponseWriter, req *http.Request, _ caddyhttp.Handler) error {
    http.Redirect(w, req, r.URL, http.StatusPermanentRedirect)
    return nil
}

Uses Go’s standard http.Redirect function with http.StatusPermanentRedirect (308).

HTTP 308 vs Other Redirect Codes

Code	Name	Method Preserved	Cache Behavior
301	Moved Permanently	No (GET/HEAD only)	Cached by browsers
302	Found	No (GET/HEAD only)	Not cached
307	Temporary Redirect	Yes	Not cached
308	Permanent Redirect	Yes	Cached by browsers

Caddy Defender uses 308 to:

Preserve POST/PUT/DELETE methods if used
Signal to crawlers this is permanent
Allow browser caching of the redirect

Use Cases

Redirect to API Documentation

Send AI scrapers to your API documentation instead of blocking:

defender redirect {
    ranges openai deepseek
    url "https://example.com/api-documentation"
}

Redirect to Contact Form

Direct potential partners to a contact form:

defender redirect {
    ranges aws gcloud azure
    url "https://example.com/contact-for-api-access"
}

Redirect to Information Page

Provide information about why access is restricted:

defender redirect {
    ranges all
    url "https://example.com/access-policy"
}

Redirect to Alternative Content

Send scrapers to a different version of your site:

defender redirect {
    ranges openai
    url "https://api.example.com/public"
}

Redirect URL Options

Absolute URLs

url "https://example.com/page"
url "https://different-domain.com"

Relative URLs

url "/api-docs"
url "/contact"

URLs with Query Parameters

url "https://example.com?source=blocked"
url "/contact?reason=scraper"

Client Behavior

How different clients handle 308 redirects:

Browsers
curl
HTTP Libraries

Automatically follow the redirect
Cache the redirect (future requests go directly to new URL)
Preserve request method (POST stays POST)

# Follow redirects with -L flag
curl -L http://example.com

# See redirect without following
curl -I http://example.com

Advantages

Informative - Can direct users to explanation pages
Professional - More polite than blocking or dropping
Flexible - Can redirect anywhere (docs, contact, etc.)
SEO-friendly - Search engines understand 308 redirects
Preserves method - POST/PUT/DELETE preserved unlike 301/302

Disadvantages

Scrapers still consume resources - They still hit your server first
May be followed - Sophisticated scrapers will follow redirects
Requires destination - Need to maintain the redirect target
Cached by browsers - Hard to change later for same clients

Comparison with Other Responders

vs Block: Redirect sends users elsewhere, Block denies access
vs Custom: Redirect changes location, Custom shows a message
vs Drop: Redirect gives direction, Drop gives nothing
vs Tarpit: Redirect is immediate, Tarpit deliberately slows down

When to Use Redirect

Use Redirect when:

You want to provide alternative resources
Directing scrapers to API docs is preferred
Professional, polite blocking is desired
You have a good destination URL

Don’t use Redirect when:

You want to minimize all scraper interaction
The destination doesn’t add value
Bandwidth conservation is critical
You want to hide that blocking is happening

Best Practices

Redirect to useful content - API docs, contact forms, policy pages
Use HTTPS URLs - Ensure redirect destination is secure
Monitor redirect destination - Ensure target URL stays valid
Consider redirect loops - Don’t create circular redirects
Test redirect behavior - Verify clients are redirected correctly

Testing

Test the Redirect responder:

# See the redirect without following
curl -I http://example.com
# Should show: HTTP/1.1 308 Permanent Redirect
# Location: https://example.com

# Follow the redirect
curl -L http://example.com

# Simulate blocked IP
curl -I -H "X-Forwarded-For: 20.202.43.67" http://example.com

Advanced Configuration

Different Redirects for Different Ranges

example.com {
    # Redirect AI companies to API docs
    defender redirect {
        ranges openai deepseek
        url "https://example.com/api-access"
    }
    
    # Redirect cloud providers to contact form
    defender redirect {
        ranges aws gcloud azure
        url "https://example.com/contact"
    }
    
    respond "Main content"
}

Redirect with Whitelist

defender redirect {
    ranges aws
    whitelist 3.5.140.2 52.94.133.131
    url "https://example.com/restricted"
}

Custom Responder - Return a message instead of redirecting
Block Responder - Block access with 403
HTTP 308 Status Code - MDN Documentation

Responders

IP Ranges

Fetchers

Overview

Configuration

HTTP Response

Examples

Implementation Details

HTTP 308 vs Other Redirect Codes

Use Cases

Redirect to API Documentation

Redirect to Contact Form

Redirect to Information Page

Redirect to Alternative Content

Redirect URL Options

Absolute URLs

Relative URLs

URLs with Query Parameters

Client Behavior

Advantages

Disadvantages

Comparison with Other Responders

When to Use Redirect

Best Practices

Testing

Advanced Configuration

Different Redirects for Different Ranges

Redirect with Whitelist

Build docs developers (and LLMs) love

Responders

IP Ranges

Fetchers

​Overview

​Configuration

​HTTP Response

​Examples

​Implementation Details

​HTTP 308 vs Other Redirect Codes

​Use Cases

​Redirect to API Documentation

​Redirect to Contact Form

​Redirect to Information Page

​Redirect to Alternative Content

​Redirect URL Options

​Absolute URLs

​Relative URLs

​URLs with Query Parameters

​Client Behavior

​Advantages

​Disadvantages

​Comparison with Other Responders

​When to Use Redirect

​Best Practices

​Testing

​Advanced Configuration

​Different Redirects for Different Ranges

​Redirect with Whitelist

​Related Documentation

Build docs developers (and LLMs) love

Overview

Configuration

HTTP Response

Examples

Implementation Details

HTTP 308 vs Other Redirect Codes

Use Cases

Redirect to API Documentation

Redirect to Contact Form

Redirect to Information Page

Redirect to Alternative Content

Redirect URL Options

Absolute URLs

Relative URLs

URLs with Query Parameters

Client Behavior

Advantages

Disadvantages

Comparison with Other Responders

When to Use Redirect

Best Practices

Testing

Advanced Configuration

Different Redirects for Different Ranges

Redirect with Whitelist

Related Documentation