API7 Docs
How-To GuidesTraffic Management

Configure Rate Limiting

Learn how to configure simple and advanced rate limiting for your APIs to prevent abuse and ensure fair usage.

Rate limiting allows you to restrict the number of requests a client can make to your APIs within a specific time window. This protects your backend services from being overwhelmed by too many requests and ensures fair usage among all users.

API7 Enterprise provides two plugins for rate limiting:

  • limit-count: A simple rate limiting plugin that counts requests within a fixed time window.
  • limit-count-advanced: An advanced version that supports sliding windows, multiple rules, and Redis Sentinel.

Prerequisites

  • An API7 Enterprise instance is running.
  • A Gateway Group is created and a Gateway instance is running.
  • A token from the Dashboard.

Configure Basic Rate Limiting

The limit-count plugin is ideal for simple rate limiting scenarios, such as limiting each IP address to 5 requests per minute.

curl -k "https://localhost:7443/apisix/admin/services/rate-limit-service?gateway_group_id={gateway_group_id}" -X PUT \
  -H "X-API-KEY: ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "rate-limit-service",
    "upstream": {
      "type": "roundrobin",
      "scheme": "http",
      "nodes": [
        {
          "host": "httpbin.org",
          "port": 80,
          "weight": 100
        }
      ]
    }
  }'

curl -k "https://localhost:7443/apisix/admin/routes/rate-limit-route?gateway_group_id={gateway_group_id}" -X PUT \
  -H "X-API-KEY: ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "rate-limit-route",
    "methods": ["GET"],
    "paths": ["/get"],
    "service_id": "rate-limit-service",
    "plugins": {
      "limit-count": {
        "count": 5,
        "time_window": 60,
        "rejected_code": 429,
        "rejected_msg": "Too Many Requests",
        "key": "remote_addr",
        "policy": "local"
      }
    }
  }'

Configure Distributed Rate Limiting

In a multi-node Gateway deployment, use the redis policy to share the rate limit counters across all nodes.

curl -k "https://localhost:7443/apisix/admin/services/distributed-rate-limit-service?gateway_group_id={gateway_group_id}" -X PUT \
  -H "X-API-KEY: ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "distributed-rate-limit-service",
    "upstream": {
      "type": "roundrobin",
      "scheme": "http",
      "nodes": [
        {
          "host": "httpbin.org",
          "port": 80,
          "weight": 100
        }
      ]
    }
  }'

curl -k "https://localhost:7443/apisix/admin/routes/distributed-rate-limit-route?gateway_group_id={gateway_group_id}" -X PUT \
  -H "X-API-KEY: ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "distributed-rate-limit-route",
    "methods": ["GET"],
    "paths": ["/get"],
    "service_id": "distributed-rate-limit-service",
    "plugins": {
      "limit-count": {
        "count": 100,
        "time_window": 60,
        "policy": "redis",
        "redis_host": "127.0.0.1",
        "redis_port": 6379,
        "redis_password": "your-password",
        "redis_database": 0,
        "allow_degradation": true
      }
    }
  }'

Set allow_degradation to true to allow traffic even if the Redis server is unreachable.

Configure Advanced Rate Limiting

The limit-count-advanced plugin supports a sliding window algorithm, which prevents traffic bursts that can occur at the boundary of fixed windows. It also allows defining multiple rules in a single plugin instance.

curl -k "https://localhost:7443/apisix/admin/services/advanced-rate-limit-service?gateway_group_id={gateway_group_id}" -X PUT \
  -H "X-API-KEY: ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "advanced-rate-limit-service",
    "upstream": {
      "type": "roundrobin",
      "scheme": "http",
      "nodes": [
        {
          "host": "httpbin.org",
          "port": 80,
          "weight": 100
        }
      ]
    }
  }'

curl -k "https://localhost:7443/apisix/admin/routes/advanced-rate-limit-route?gateway_group_id={gateway_group_id}" -X PUT \
  -H "X-API-KEY: ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "advanced-rate-limit-route",
    "methods": ["GET"],
    "paths": ["/get"],
    "service_id": "advanced-rate-limit-service",
    "plugins": {
      "limit-count-advanced": {
        "window_type": "sliding",
        "rules": [
          {
            "count": 10,
            "time_window": 1,
            "key": "remote_addr"
          },
          {
            "count": 1000,
            "time_window": 3600,
            "key": "remote_addr"
          }
        ]
      }
    }
  }'

In this example, a client is limited to 10 requests per second and 1,000 requests per hour.

Validate the Configuration

Send multiple requests to the configured route to trigger the rate limit:

for i in {1..6}; do curl -I "http://127.0.0.1:9080/get"; done

When the limit is reached, you will receive a 429 Too Many Requests (or your custom rejected_code) response.

If the route returns 404 immediately after you apply the configuration, wait a few seconds for the latest configuration to reach the gateway and retry.

The response will also include X-RateLimit headers if show_limit_quota_header is enabled (default is true):

HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 5
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 45

Troubleshooting

  • Redis Connection Issues: Ensure the Gateway nodes have network access to the Redis server and that the credentials are correct. Check the Gateway logs for connection errors.
  • Wrong key_type: If you use a variable for the key, ensure key_type is set to var. If you use a constant string, set it to constant.
  • Latency with Redis: If Redis latency is affecting request performance, consider using the local policy for high-frequency low-latency limits, or tune the sync_interval for redis-based policies.

Next Steps

Forward External Auth User Info to Upstream

Previous Page

Improve Rate Limiting Accuracy Across Gateway Instances

Next Page