Deprecation of Rate Limiting V1 — 2nd November, 2026

Applicable to: Tenant admins who have rate limit rules defined as type: gateway-rate-limiting-config (Rate Limiting V1). If you only use Rate Limiting V2 (tenant-rate-limit-config/model or tenant-rate-limit-config/mcp), this change does not affect you.Deprecation: Rate Limiting V1 is deprecated and will be fully removed on 15th December, 2026. Existing V1 rules keep working until then. Recreate them in V2 before that date.

What Is Changing

Rate Limiting V1, the single gateway-rate-limiting-config document holding an ordered rules list, is deprecated. Rate Limiting V2 replaces it with one named limit per config. Both systems currently run in parallel: V1 is checked first, and V2 is consulted only when no V1 rule blocks the request. Existing V1 rules continue to be enforced during the transition, but new rate limits should be created in V2.

Why This Change

V1 enforced only the first matching rule in a list, so which limit applied to a request depended on rule order, and usage was still counted against every rule the request matched. This made limits hard to reason about and led to shared buckets being saturated by traffic that was never blocked by them. V2 addresses these gaps:

Predictable evaluation: every matching limit must allow a request, so limits compose without depending on order.
Richer limits: several windows (requests and tokens, per minute, hour, and day) on one limit, NOT IN exclusions, provider account filters, and per-entity overrides.
Safe rollout: audit and soft_enforce modes let you validate a limit before enforcing it.
MCP coverage: rate limit tools/call requests through the MCP Gateway.

What You Need to Do

Audit your existing V1 rules

List every rule in your gateway-rate-limiting-config: its when filters, limit_to and unit, and rate_limit_applies_per. Note which rules depended on ordering, where a specific rule was placed above a generic one.

Recreate each rule in V2 in audit mode

Go to AI Gateway → Policies → Rate Limiting v2 and create an equivalent limit for each V1 rule, using Apply as YAML if you prefer to paste the config. Start with mode: audit to confirm the limit matches the traffic you expect. See the field mapping below.

Account for the change in matching behavior

In V1, only the first matching rule blocks a request. In V2, every matching limit is enforced. If a generic V1 rule sat below a specific one, narrow the V2 limit with NOT IN filters, or use per-entity overrides, so the specific traffic is not capped twice.

Switch to enforce, then delete the V1 rule

Once a V2 limit behaves correctly in audit mode, set mode: enforce and delete the corresponding V1 rule. V2 counters start from zero and do not inherit V1 usage, and a request matching both a V1 rule and a V2 limit is counted and blockable by both until you remove the V1 rule.

Field Mapping

V1 (`gateway-rate-limiting-config`)	V2 (`tenant-rate-limit-config/model`)
`rules[].id`	Top-level `name`. Must be unique, so rules that share an `id` in V1 need distinct names
`when.subjects: ["user:alice@example.com"]`	`when.subjects.users.in: [alice@example.com]`
`when.subjects: ["team:backend"]`	`when.subjects.teams.in: [backend]`
`when.subjects: ["virtualaccount:ci-bot"]`	`when.subjects.virtual_accounts.in: [ci-bot]`
`when.models`	`when.models.in`
`when.metadata: {environment: production}`	`when.metadata.environment.in: [production]`
`limit_to` + `unit`	`limits.<unit>: <value>`. One limit can hold several units
`rate_limit_applies_per: ['user']`	`applies_to.type: per-user`
`rate_limit_applies_per: ['model']`	`applies_to.type: per-model`
`rate_limit_applies_per: ['virtualaccount']`	`applies_to.type: per-virtual-account`
`rate_limit_applies_per: ['metadata.project_id']`	`applies_to.type: metadata` with `applies_to.metadata: project_id`
Not supported	`mode`: `enforce`, `audit`, or `soft_enforce`

V2 partitions a limit on exactly one dimension, fixed at creation. A V1 rule with two values in rate_limit_applies_per, such as ['user', 'model'], has no direct V2 equivalent. Split it into separate limits, or choose the dimension that matters most, before the removal date.

Example

A V1 rule that gives every user in the backend team 1,000,000 tokens per day on gpt-4o in production:

name: ratelimiting-config
type: gateway-rate-limiting-config
rules:
  - id: per-user-gpt4o
    when:
      subjects: ["team:backend"]
      models: ["openai-main/gpt-4o"]
      metadata:
        environment: production
    limit_to: 1000000
    unit: tokens_per_day
    rate_limit_applies_per: ["user"]

The equivalent V2 limit, created in audit mode first:

type: tenant-rate-limit-config/model
name: per-user-gpt4o
when:
  subjects:
    teams:
      in:
        - backend
  models:
    in:
      - openai-main/gpt-4o
  metadata:
    environment:
      in:
        - production
limits:
  tokens_per_day: 1000000
applies_to:
  type: per-user
mode: audit

For the full list of filters, windows, and overrides, see the Rate Limiting V2 YAML reference.

Timeline

Milestone	Date
Deprecation announcement	2nd November, 2026
Rate Limiting V1 (`gateway-rate-limiting-config`) fully removed	15th December, 2026

Migrate to Rate Limiting V2 well ahead of 15th December, 2026. Rate limits that exist only in V1 will stop being enforced after that date, which leaves the traffic they covered unthrottled.

References

If you have questions about the migration or run into anything unexpected, reach out to support@truefoundry.com.

​What Is Changing

​Why This Change

​What You Need to Do

​Field Mapping

​Example

​Timeline

​References

What Is Changing

Why This Change

What You Need to Do

Field Mapping

Example

Timeline

References