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

# Quick Start

> Add a rate limiter binding to an Edge Compute function, deploy it, and verify its behavior.

This walkthrough configures a function to allow two requests per authenticated user during each 10-second window.

<Note>
  Use `telnyx-edge` v0.4.0 or later. Earlier versions may upload an invalid `[[ratelimits]]` block instead of rejecting it locally, and do not generate the binding's type.
</Note>

## 1. Start from a project

This walkthrough uses a `telnyx.toml` project, where the runtime serves your `fetch` handler. `new-func --actor` scaffolds one:

```bash theme={null}
telnyx-edge new-func -l ts -n my-api --actor
cd my-api
npm install          # pulls in @telnyx/edge-runtime
```

Every command below runs from the project directory.

<Note>
  It works in a `func.toml` project too — keep your own HTTP server and reach the binding with `import { env } from "@telnyx/edge-runtime"`.
</Note>

## 2. Declare a rate limiter

Add a `[[ratelimits]]` block to `telnyx.toml`, alongside whatever else the project declares:

```toml theme={null}
name = "my-api"
main = "src/index.ts"
compatibility_date = "2026-05-01"

[[actors]]
binding = "COUNTER"
type = "Counter"

[[ratelimits]]
name = "API_LIMIT"
limit = 2
period = 10

[edge_compute]              # written by new-func — leave it as generated
func_id = "..."
func_name = "my-api"
```

This configuration allows two successful checks per key in each 10-second window.

## 3. Check the limit in your handler

Generate the binding's type first, so `env.API_LIMIT` is typed for you. It is written into `telnyx-env.d.ts` alongside every other binding the manifest declares, so a project that also hosts an actor gets both in one `Env`:

```bash theme={null}
telnyx-edge types   # writes telnyx-env.d.ts; needs telnyx-edge v0.4.0+ and @telnyx/edge-runtime 0.9.2+
```

```ts theme={null}
// Keep the scaffold's actor export: telnyx.toml still declares type = "Counter",
// and the runtime loads that class from this module.
export { Counter } from "./counter";

export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    // Only trust this header when an authenticated upstream sets it.
    const userId = request.headers.get("x-authenticated-user-id");
    if (!userId) {
      return Response.json({ error: "Unauthorized" }, { status: 401 });
    }

    const { success } = await env.API_LIMIT.limit({ key: userId });
    if (!success) {
      return Response.json(
        { error: "Rate limit exceeded" },
        {
          status: 429,
          headers: { "Retry-After": "10" },
        },
      );
    }

    return Response.json({ ok: true });
  },
};
```

The binding returns a decision; it does not send a `429` response automatically.

## 4. Ship and test

```bash theme={null}
telnyx-edge ship
```

For the configuration above, three requests with the same trusted user ID during one window produce two `200` responses followed by a `429`:

```bash theme={null}
curl -i -H 'x-authenticated-user-id: user-123' https://<function-url>
curl -i -H 'x-authenticated-user-id: user-123' https://<function-url>
curl -i -H 'x-authenticated-user-id: user-123' https://<function-url>
```

The CLI validates each declared limiter before upload and prints its name, limit, and period.

See the [API Reference](/docs/edge-compute/rate-limiting/api-reference) for the binding's method contract and return values.