Skip to main content

​
Overview

The ratelimit responder marks requests from specific IP ranges for rate limiting, integrating seamlessly with the caddy-ratelimit module. This allows you to apply different rate limits to different IP ranges.
The ratelimit responder requires the caddy-ratelimit module to be installed and configured.

​
When to Use

Use the ratelimit responder when:
  • You want to slow down, not block, specific IP ranges
  • You need different rate limits for different traffic sources
  • You want to throttle AI scrapers or bot traffic
  • You want to protect APIs from abuse while allowing limited access

​
How It Works

  1. Caddy Defender marks requests from specified ranges
  2. The mark is detected by caddy-ratelimit via a header or matcher
  3. caddy-ratelimit applies the configured rate limit rules
  4. Requests exceeding the limit receive appropriate responses

​
Configuration Example

{
    order rate_limit after basic_auth
}

:80 {
    defender ratelimit {
        ranges private
    }

    rate_limit {
        zone static_example {
            match {
                method GET
                header X-RateLimit-Apply true
            }
            key {remote_host}
            events 3
            window 1m
        }
    }

    respond "Hey I'm behind a rate limit!"
}
This configuration:
  • Marks requests from private IP ranges for rate limiting
  • Applies a rate limit of 3 requests per minute
  • Uses the remote host as the rate limit key
  • Only applies to GET requests with the X-RateLimit-Apply header

​
Rate Limit Configuration

The rate_limit block supports several configuration options:
OptionDescriptionExample
zoneNamed rate limit zonezone api_limit { ... }
matchRequest matcher (method, header, path)method GET
keyWhat to rate limit by{remote_host}, {http.request.header.API-Key}
eventsNumber of allowed requests3, 100
windowTime window for the limit1m, 1h, 24h

​
Real-World Examples

api.example.com {
    # Mark AI scrapers for aggressive rate limiting
    defender ratelimit {
        ranges openai anthropic
    }

    rate_limit {
        zone ai_limit {
            match {
                header X-RateLimit-Apply true
            }
            key {remote_host}
            events 10
            window 1h
        }
    }

    respond "API endpoint"
}

​
Rate Limit Keys

You can rate limit based on different request attributes: 
key {remote_host}

​
Advanced Integration

For complete rate limiting documentation, see the Rate Limiting Configuration and caddy-ratelimit documentation.

​
Custom Headers

You can customize which header caddy-ratelimit looks for: 
defender ratelimit {
    ranges openai
    # Custom header can be configured in defender if supported
}

rate_limit {
    zone custom {
        match {
            header X-Custom-RateLimit true
        }
        key {remote_host}
        events 50
        window 1h
    }
}

​
Multiple Zones

Apply different rate limits to different scenarios: 
defender ratelimit {
    ranges aws google-cloud
}

rate_limit {
    # Strict limit for API endpoints
    zone api_strict {
        match {
            path /api/*
            header X-RateLimit-Apply true
        }
        key {remote_host}
        events 10
        window 1m
    }

    # Lenient limit for static assets
    zone static_lenient {
        match {
            path /static/*
            header X-RateLimit-Apply true
        }
        key {remote_host}
        events 100
        window 1m
    }
}

Build docs developers (and LLMs) love

Get started for freeTalk to us