> ## Documentation Index
> Fetch the complete documentation index at: https://developers.telnyx.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

```ts theme={null}
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`.

```ts theme={null}
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:

```ts theme={null}
interface RateLimiter {
  limit(options: { key: string }): Promise<{ success: boolean }>;
}

interface Env {
  API_LIMIT: RateLimiter;
}
```

See [Rate Limiting](/docs/edge-compute/rate-limiting) for configuration, usage patterns, and platform behavior.