Rate Limiting

Enforce per-key request budgets in bundled Edge Compute functions with a platform-managed rate limiter binding.

A rate limiter binding caps how many requests a key can make during a fixed window. Your function chooses the key—for example, an authenticated user ID, tenant ID, or hashed API-key identifier—and decides how to respond when the budget is exhausted.

Rate limiters are available to JavaScript and TypeScript functions in either project shape. In a telnyx.toml project the binding arrives on the handler’s env argument as env.<NAME>; in a func.toml project reach it with import { env } from "@telnyx/edge-runtime". You don’t create a KV namespace or manage counter storage.

Start with the Quick Start to add a rate limiter to a function and test it in production.

Configuration reference

Field	Type	Required	Description
name	string	Yes	Binding name. The platform uppercases it and replaces hyphens with underscores, so api-limit is exposed as env.API_LIMIT. The resulting handle must start with a letter or underscore, contain only letters, numbers, and underscores, and be unique across all bindings in the manifest.
limit	integer	Yes	Maximum number of successful checks per key and window. Must be greater than zero.
period	integer	Yes	Fixed-window duration in seconds. The supported values are 10 and 60.
namespace_id	string	No	Groups counters across functions: functions declaring the same namespace_id and the same name count against one budget, and omitting it gives each function its own. A positive integer written as a string, such as "1001" — it is not a KV namespace ID, and rate limiter counters never occupy one of your KV namespaces. Set limit and period identically in every function sharing a group; they are read per function, so a mismatch means one starts rejecting at another’s threshold.

The period is an integer, not a duration string: use period = 60, not period = "60s".

Configuration changes take effect after the next telnyx-edge ship.

Multiple rate limiters

Each [[ratelimits]] block has an independent counter namespace. This lets one function apply different budgets to different plans or operations:

[[ratelimits]]
name = "FREE_TIER"
limit = 100
period = 60

[[ratelimits]]
name = "PAID_TIER"
limit = 1000
period = 60

type Tier = "free" | "paid";

async function checkPlanLimit(
  env: { FREE_TIER: RateLimiter; PAID_TIER: RateLimiter },
  userId: string,
  tier: Tier,
): Promise<boolean> {
  const limiter = tier === "paid" ? env.PAID_TIER : env.FREE_TIER;
  const result = await limiter.limit({ key: userId });
  return result.success;
}

Derive both userId and tier from authenticated, trusted application state. A caller-controlled header or query parameter lets a client choose a fresh key and bypass its intended budget.

Choose keys carefully

Key	When to use it
Authenticated user ID	Give every signed-in user an independent budget.
Tenant ID	Share one budget across all users in a tenant.
Hashed API-key ID	Limit an API credential without placing the raw secret in a counter key.
Composite key such as tenant:endpoint	Apply separate budgets to operations or routes.
IP address	Not usable today. The caller’s address is not propagated to your function — x-forwarded-for and x-real-ip both carry platform-internal addresses, and the first x-forwarded-for hop varies between requests, so each request would consume a different budget.

Avoid putting secrets or other sensitive values directly in a key.

Behavior and limitations

Behavior	Detail
Per-site counters	Each Edge Compute site enforces its own budget. Requests served from different sites do not share a global counter.
Fixed windows	Windows align to 10-second or 60-second clock boundaries. A client can use the end of one window and the start of the next, allowing a short burst of up to twice the configured limit.
Platform-managed storage	Counters live in an internal per-site KV bucket and survive a function pod restart. It is not one of your KV namespaces — you never create, list, or delete it, and keys expire on their own.
Request latency	An allowed check reads and updates the backing counter. A check already known to be over limit may be rejected from an in-process cache. Do not assume every call is network-free.
Fails open	If the counter store cannot be reached, checks return success: true and requests are admitted. An outage means traffic is unlimited, not rejected.
Concurrent first requests	Rate limiting is not a strict concurrency barrier. Simultaneous first checks for a previously unseen key can temporarily exceed the configured limit while its counter is initialized. Do not use this binding as the only control for hard financial, inventory, or security quotas.
No sliding window	V0 supports fixed windows only.
No global enforcement	V0 does not coordinate one budget across all sites.

Related resources

• Quick Start — Configure, deploy, and test a rate limiter
• API reference — Runtime method inputs, return values, and failure behavior
• Bindings — How runtime resource handles are declared and resolved
• Configuration — The complete telnyx.toml reference
• Deploy a function — Ship configuration and code changes