Skip to main content
A rate limit policy tells the gateway to count requests over a fixed window, such as 100 per minute, and reject the extra ones before they reach your . This works without API keys. You choose what to count by, such as the client IP or a header. For limits per API key, use the ratelimits setting on the API key authentication policy instead. To add one, open the app, go to Policies, click Add Policy, and pick Rate Limit. The form starts at 100 requests per 60 seconds per client IP.

​
Settings

​
integer
required
Maximum requests per window for each caller (or each group you count by). At least 1.
​
integer
required
Window length in milliseconds. At least 1.
​
RatelimitIdentifier[]
required
1 to 5 things to count by. Each unique combination of values gets its own counter, with the same limit and windowMs. Each entry sets exactly one of:
  • remoteIp: {}: the client IP.
  • header: { name }: the value of a request header.
  • path: {}: the request path.
  • authenticatedSubject: {}: the caller’s subject, from an earlier API key policy.
  • principalField: { path }: a field in the principal, as a dotted path like source.key.meta.org_id, up to 512 characters. Only string values work.
The older single identifier field still works, but responses always return identifiers. Don’t set both.
Example: 100 requests per minute per subject on each path

​
When a value is missing

If a value can’t be found, such as a missing header or no caller on an anonymous request, it counts as unknown. All requests missing that value share one counter. For example, with [authenticatedSubject, path], anonymous callers are still limited per path, together. If none of the values can be found, the request is rejected with 429 rate_limited and the message Rate limit configuration error. Unable to identify the request. So a policy that counts by a header rejects every request on a route where callers never send it. authenticatedSubject and principalField need an API key authentication policy earlier in the list. Put the rate limit after it. Every request counts as 1. Replacing the policy list with gateway.setPolicies resets every counter once the next deployment is live.

​
What callers see

Over the limit, the caller gets 429 rate_limited with Rate limit exceeded. Please try again later. If rate limiting itself fails, the request is rejected with 500 internal_server_error, not let through. Responses to requests the policy applies to include X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset (Unix seconds). A 429 also has Retry-After in whole seconds, at least 1. If an API key policy already set these headers for a per-key limit, the rate limit policy only replaces them when its result is stricter.

​
Next steps

API key authentication policy

Per-key limits and the principal that authenticatedSubject reads.

Gateway policies

Match expressions and evaluation order.
Last modified on September 29, 2026