> ## 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.3.0 or later. Earlier CLI versions may upload an invalid `[[ratelimits]]` block instead of rejecting it locally.
</Note>

## 1. Declare a rate limiter

Add a `[[ratelimits]]` block to `telnyx.toml`:

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

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

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

## 2. Check the limit in your handler

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

interface Env {
  API_LIMIT: RateLimiter;
}

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.

<Note>
  `telnyx-edge types` v0.3.0 does not yet generate rate limiter declarations. Define the small `RateLimiter` interface in your project, as shown above.
</Note>

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