RateLimit

Gateway rate limiting policy

RateLimit defines gateway-level rate limiting with configurable identifiers. Frontline executes Sentinel RateLimit policies and delegates counter state to rate limiting, so policy execution uses the same distributed counters as API and Frontline rate-limit checks.

Fields

limit · int64

Maximum number of requests allowed in the time window.

window_ms · int64

Time window in milliseconds. For example, limit: 100 with window_ms: 60000 means 100 requests per minute.

identifier · RateLimitIdentifier

Determines how requests are bucketed for rate limiting.

Examples

Per IP

{
  "policies": [
    {
      "id": "global-ratelimit",
      "name": "Rate limit by IP",
      "enabled": true,
      "match": [],
      "ratelimit": {
        "limit": 1000,
        "window_ms": 60000,
        "identifier": { "remote_ip": {} }
      }
    }
  ]
}

Per authenticated subject

{
  "policies": [
    {
      "id": "user-ratelimit",
      "name": "Rate limit per user",
      "enabled": true,
      "match": [],
      "ratelimit": {
        "limit": 500,
        "window_ms": 60000,
        "identifier": { "authenticated_subject": {} }
      }
    }
  ]
}

Requires a KeyAuth or JWTAuth policy earlier in the list to set the Principal.

Per header value

{
  "policies": [
    {
      "id": "tenant-ratelimit",
      "name": "Rate limit per tenant",
      "enabled": true,
      "match": [],
      "ratelimit": {
        "limit": 5000,
        "window_ms": 60000,
        "identifier": { "header": { "name": "X-Tenant-Id" } }
      }
    }
  ]
}

Use only when the header is set by a trusted upstream proxy.

Per principal field

{
  "policies": [
    {
      "id": "org-ratelimit",
      "name": "Rate limit per organization",
      "enabled": true,
      "match": [],
      "ratelimit": {
        "limit": 10000,
        "window_ms": 60000,
        "identifier": { "principal_field": { "path": "source.key.meta.org_id" } }
      }
    }
  ]
}

Creates a shared bucket for all keys that resolve to the same org_id meta value. The path is a dotted route into the Principal JSON — for JWT-authenticated traffic you might use source.jwt.payload.org_id instead.

Per path

{
  "policies": [
    {
      "id": "path-ratelimit",
      "name": "Rate limit per endpoint",
      "enabled": true,
      "match": [
        { "path": { "path": { "prefix": "/v1/" } } }
      ],
      "ratelimit": {
        "limit": 100,
        "window_ms": 60000,
        "identifier": { "path": {} }
      }
    }
  ]
}

Creates a separate bucket per URL path, protecting expensive endpoints without a separate policy for each.

Identifier sources

Source	Description
remote_ip	Client IP address. Effective for anonymous traffic, but can over-limit behind shared NATs.
header	Value of a named request header. Only use behind trusted proxies that set the header.
authenticated_subject	Principal subject from an upstream auth policy. Most accurate for authenticated APIs.
path	Request URL path. Creates a separate bucket per endpoint.
principal_field	Value resolved from a dotted path into the Principal JSON (for example, source.key.meta.org_id for per-organization limits).