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

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

```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` v0.3.0 does not yet generate rate limiter declarations. Define the binding interface in your project:

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