API Reference

Check a Telnyx Edge Compute rate limiter binding and interpret its result.

Each [[ratelimits]] entry exposes a rate limiter binding on env — as the handler’s env argument in a telnyx.toml project, or through import { env } from "@telnyx/edge-runtime" in a func.toml one. 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. It consumes one unit from the key’s budget, unless the counter store was unreachable — see fail-open below, where the request is admitted without being counted.
{ success: false }	The key has reached its limit for the current window.

Treat success: false as a rejection.

Rate limiting fails open: if the counter store is unreachable the check returns { success: true } and the request is admitted, so an outage means requests are not limited rather than all being rejected.

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 writes the binding’s declaration into telnyx-env.d.ts, so env.<NAME> is typed for you. It requires @telnyx/edge-runtime 0.9.2 or later, the first release exporting RateLimiter. The generated shape is:

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

interface Env {
  API_LIMIT: RateLimiter;
}

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