Rate Limiting

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 bundled JavaScript and TypeScript functions that use telnyx.toml. Each binding is exposed on the handler’s env argument as env.<NAME>. 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`.

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	Use cautiously. NATs, proxies, and carrier networks can put many users behind one address, while distributed clients can rotate addresses.

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 are stored in an internal per-site KV bucket and survive an individual function pod restart. You cannot list or access this bucket.
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.
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.

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

Overview

Get Started

Best Practices

Guides

Local Development

Configuration

CI/CD

Runtime APIs

Observability

CLI

Platform

For AI Agents

Configuration reference

Multiple rate limiters

Choose keys carefully

Behavior and limitations

​Configuration reference

​Multiple rate limiters

​Choose keys carefully

​Behavior and limitations

​Related resources

Configuration reference

Multiple rate limiters

Choose keys carefully

Behavior and limitations

Related resources