API Reference

Each [[ratelimits]] entry in telnyx.toml exposes a rate limiter binding on the handler’s env argument. The binding name is uppercased and hyphens are replaced with underscores, so a limiter named api-limit is available as env.API_LIMIT.

`env.NAME.limit({ key })`

Checks and increments the counter for key in the current fixed window.

const result = await env.API_LIMIT.limit({ key: "tenant-42:user-123" });

Input

Input	Type	Description
`key`	string	Caller-supplied identifier whose budget is independent of every other key.

Return value

The method returns Promise<{ success: boolean }>:

Value	Meaning
`{ success: true }`	The call was accepted and consumed one unit from the key’s budget.
`{ success: false }`	The key is at its limit, the counter service could not complete the check, or contention could not be resolved.

Rate limiting fails closed: treat success: false as a rejection. The binding returns only the decision. Your function is responsible for returning an appropriate response, such as HTTP 429 Too Many Requests.

const { success } = await env.API_LIMIT.limit({ key: userId });

if (!success) {
  return Response.json(
    { error: "Rate limit exceeded" },
    {
      status: 429,
      headers: { "Retry-After": "10" },
    },
  );
}

TypeScript type

telnyx-edge types v0.3.0 does not yet generate rate limiter declarations. Define the binding interface in your project:

interface RateLimiter {
  limit(options: { key: string }): Promise<{ success: boolean }>;
}

interface Env {
  API_LIMIT: RateLimiter;
}

See Rate Limiting for configuration, usage patterns, and platform behavior.

Overview

Get Started

Best Practices

Guides

Local Development

Configuration

CI/CD

Runtime APIs

Observability

CLI

Platform

For AI Agents

`env.NAME.limit({ key })`

Input

Return value

TypeScript type

​env.NAME.limit({ key })

​Input

​Return value

​TypeScript type

`env.NAME.limit({ key })`

Input

Return value

TypeScript type