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.

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.

1. Start from a project

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

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.

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

2. Declare a rate limiter

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

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:

telnyx-edge types   # writes telnyx-env.d.ts; needs telnyx-edge v0.4.0+ and @telnyx/edge-runtime 0.9.2+

// 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

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:

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 for the binding’s method contract and return values.