Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Rate limit settings

Platform-level limits, applied per client identity. Per-channel limits are separate and live in the channel’s config_json in the database.

Synopsis

[rate_limit]
enabled = false
default_rps = 100
default_burst = 50
trusted_proxies = []

[rate_limit.endpoints]
admin_rps = 20
# data_rps = …   # no default

Options

SettingDefaultEnv varWhen to change
rate_limit.enabledfalseORION_RATE_LIMIT__ENABLEDEnable on any internet-facing instance.
rate_limit.default_rps100ORION_RATE_LIMIT__DEFAULT_RPSSustained requests per second per client.
rate_limit.default_burst50ORION_RATE_LIMIT__DEFAULT_BURSTBurst allowance above the sustained rate.
rate_limit.trusted_proxies[]ORION_RATE_LIMIT__TRUSTED_PROXIESSet this if Orion sits behind a load balancer, whether or not rate_limit.enabled is on; see trusted_proxies.
rate_limit.endpoints.admin_rps20ORION_RATE_LIMIT__ENDPOINTS__ADMIN_RPSSeparate limit for the admin API. Set the variable to an empty string to clear it, which makes the admin plane use default_rps.
rate_limit.endpoints.data_rps—ORION_RATE_LIMIT__ENDPOINTS__DATA_RPSSeparate limit for the data plane; unset means it uses default_rps. Set the variable to an empty string to clear it.

trusted_proxies

The setting changes behaviour for every proxied deployment. The direct peer IP is authoritative. X-Forwarded-For and X-Real-IP are honoured only when the peer address falls inside one of these CIDR blocks. Bare IPs are accepted and treated as /32 or /128. The default is empty, which means forwarded headers are never trusted. When the peer is trusted, the client is the rightmost X-Forwarded-For hop that is not itself a trusted proxy: the hop your own proxy appended. The leftmost elements arrive from the client verbatim and are never used, so a forged prefix cannot mint an identity.

The consequence in both directions:

  • Behind a load balancer with this unset, every request appears to come from the balancer, so all clients share a single rate-limit bucket and the limit effectively applies to your whole fleet at once. List the balancer’s subnet — trusted_proxies = ["10.0.0.0/8"] — to get per-client limiting back.
  • List a network you do not control and clients on it can spoof X-Forwarded-For to mint a fresh bucket per request, which is exactly no rate limiting at all. List only the addresses of proxies you operate.

It applies even with rate_limit.enabled = false. The key is spelled under [rate_limit], but what it configures is “may a forwarded header name the client”. Four consumers resolve the caller’s address with it: the platform rate limiter, the failed-admin-auth backoff, audit rows’ client_ip, and per-channel rate_limit blocks. The full reasoning is in Design Notes › Why forwarded headers are ignored by default.

Both endpoint limits are optional, so their environment variables are three-state. Unset leaves the config-file value alone, a number sets the limit, and an empty string clears it back to “use default_rps”.

Last verified 14 September 2026