Limit Plans
Every screen and endpoint here — plans, the Limits tab on identities, and Bulk Assignment — is governed by the Identity permission group (see Access Control and Roles): View to read, Manage to write. The AI Budgets permission group is also accepted in place of Identity, so an installation still organized around the older AI Budgets model keeps working unchanged.
Neither plan type is gated on a license module, at the API level or on screen: API Request Count and AI Token Limit plans are created, listed, activated and assigned through the screens, the Management API and APIops on an installation whose license does not name AI Gateway exactly like on a licensed one. The type selector of the new plan dialog and of an identity's Limits tab offers both types, and the plan list shows both tabs. What the module still governs is the menu: Limit Plans is always listed under Identity Management; the AI Gateway menu group lists it as well only for a project member who cannot open Identity Management, and that group itself is hidden without the module. The type of an existing plan is read-only in any case.
Concepts
A limit plan is a reusable description of a limit. It says what is limited (APIs, endpoints, LLM Gateways, models, providers), how much, and what happens when the limit is reached. A plan limits only while it is active, and only the callers in its target audience.
| Concept | Meaning |
|---|---|
| Limit Plan | A named, reusable set of limits. Defined once, used by any number of identities. When an active plan is saved, everyone on it gets the new values at once. |
| Target Audience | The callers the plan limits: identities you select on the plan page, callers that match a condition, and identities that pick the plan on their own Limits tab. |
| Status | Active or Inactive. An active plan applies on the gateways, and every save reaches them at once. An inactive plan limits nothing. |
| Limits tab | The tab on an organization, consumer, application or API client where you add a plan to that identity and see which plans apply to it. |
Plan Types
A plan has one of two types, chosen when the plan is created. The type cannot be changed afterwards.
AI Token Limit — token limits, USD budgets and request-count limits, each per minute/hour/day/month, alert thresholds and a hard cap on every limit, and an action for when a limit is reached. Every limit names its target: one LLM Gateway, one model of one LLM provider, or one provider. A plan has no limit of its own that covers all AI traffic of an identity.
API Request Count — the limit body is a list of windows; each window defines:
| Field | Meaning | Default |
|---|---|---|
| Requests | The number of requests permitted in the window (a positive integer). | — |
| Every | How many units make up one window — for example, a 5-minute window is Every 5 with the unit minute. Empty means 1. | 1 |
| Unit | The unit of time the window is measured in: second, minute, hour, day or month. | — |
| Window Type | Fixed (calendar aligned) resets the counter on a calendar boundary, for example at the start of each minute; Sliding counts the requests of the last period before each request, so there is no burst at a window boundary: a client that used its whole limit at the end of one minute cannot send the same number again at the start of the next. | Fixed |
| Counting Mode | All requests counts every request, accepted or rejected, on every limit it reaches, so a client that keeps sending over the limit stays blocked longer. On a Sliding period its rejected requests stay in the last period, and a request that the minute limit rejects still uses the day limit; on a Fixed period both modes block the same requests until the period ends. Accepted only counts only requests that reach the backend — the right choice for a commercial quota. | All requests |
| Limit Change Action | What happens to the current usage counter when this limit itself changes: Clamp to previous limit, Reset (applies only when the limit increases) or Leave unchanged (the counter keeps its value and the new limit applies from the next request; if the counter has already reached the new limit, requests stay rejected until the period ends). | Leave unchanged |
A limit needs at least one window. The same Every/Unit combination cannot be defined twice in the same limit — the screen warns before you can save. "100 requests per second and 10,000 per day" is one limit with two windows: exceeding any one of them blocks the request. An hour, day or month window answers with a quota error; a second or minute window answers with a throttling error.
The Limit Plans Screen
Reached from Identity Management → Limit Plans. A project member who cannot open Identity Management finds it under AI Gateway → Limit Plans instead.
The screen lists every plan of the menu's scope in one table. Each row shows the plan's Name (with its description below), Type, Identify By, Target Audience (with the number of pending identities, if any), Status (Active or Inactive) and Last Updated (date, time and user); under Administration, a Project column is added. Clicking a row opens the plan page; the row's "⋯" menu holds Edit, Export, Duplicate, Audit and Delete. The table shows 10 plans a page by default (10, 25, 50 or 100).
Above the table, these filters narrow the list; the eraser button clears them:
| Filter | Narrows to |
|---|---|
| Search | Name or description |
| All API proxies / All AI proxies | Plans whose limits reach the selected API proxies or LLM Gateways |
| All types | API Request Count or AI Token Limit; under Administration also Subscription plan (see Profiles Owned by a Subscription Plan) |
| All identification methods | Authentication or Request Variable |
| All statuses | Active or Inactive |
| All projects | Administration only: one or more projects, or the administration catalog (admin) |
| All portals | Administration only: the subscription plan profiles of the selected portals |
The breadcrumb offers Bulk assignment, Import and Create (see Bulk Assignment).
When nothing matches, the screen shows one of two messages:
| Situation | What you see |
|---|---|
| No plan exists in this scope | "No limit plans defined yet." |
| A filter matches nothing | "No limit plan matches this filter.", a line naming how many plans are defined in this scope, and a Clear filters button that resets every filter together |
Plan Scope: Project or Administration Catalog
Every plan belongs either to one project's own catalog or to the administration catalog — the plans every project can use, shown as admin in the project filter.
- The project menu lists only the active project's own plans. A plan of the administration catalog is not listed there, but a project member can add it to the identities of their project from the Limits tab, where it carries an Admin plan badge. Only a system administrator can create, edit, activate, deactivate or delete one, from Administration.
- A new plan is created in the scope of the menu you are in: Create in the project menu creates a project plan; Create under Administration creates a plan of the administration catalog.
A Subscription Plan on a portal API Product can only reference an active, platform-scope plan of the matching type — this is what makes the administration (Platform) catalog the shared source of ceilings a commercial plan sells.
Administration Mode: Every Project in One List
A system administrator also reaches the plans from Administration → Identity Management → Limit Plans. This view does not belong to any one project: it lists every project's plans and the administration catalog together, so a plan can be found and corrected without first switching into the project that owns it.
- The All projects filter above the list narrows it to one or more projects, or to the administration catalog (admin). Plans stay project-scoped — the filter only decides what is shown; it never moves a plan between projects.
- Editing a row opens the same plan page as in project mode, in the project that owns the plan. Activating, deactivating and deleting work exactly as they do there.
- Bulk assignment here assigns the plans of the administration catalog to the identities of every project (for its use in the project menu, see Bulk Assignment).
- A user who is not a system administrator sees only the administration catalog in this menu.
Profiles Owned by a Subscription Plan
When a portal subscription plan carries a rate limit or a quota, the system generates an API Request Count profile for that plan and updates it whenever the plan's numbers change. These profiles live in the administration catalog too, but they do not behave like ordinary plans:
- They are listed only on the Administration screen, with a lock icon. Each row names the subscription plan, with its API product and portal below; the Subscription plan type and the All portals filter narrow the list to them. The plan page is badged Subscription plan.
- They cannot be edited or deleted. The only way to change these limits is the rate-limit and quota fields on the owning subscription plan. The screen says: "This limit profile is managed by the subscription plan".
- They are not offered when you add a plan to an identity or run a bulk assignment — the owning plan rewrites them from its own numbers, so binding another identity to one would silently change that identity's ceiling.
- If the subscription plan is deleted — or its rate limit and quota are both cleared — its profile is released, not removed: it stays active, keeps applying to the identities that already use it, and becomes an ordinary catalog plan that you can edit, deactivate or add to identities. Its description is rewritten to name the plan it came from and the date it was released.
- The profile's internal key includes the owning API Product's name as well as the plan's, so two products that each have a plan named, for instance, "Standard" get two distinct profiles instead of colliding on the same one. Profiles generated before this change keep their existing key.
- A profile has one limit for each API of the product — like every plan, it has no limit of its own that covers all APIs.
- On an installation upgraded from an earlier version, profiles that this mechanism had already generated but had not yet marked as owned are found and stamped with their owning plan automatically; any plan that had ended up bound to another plan's profile because of that gap is moved back to its own. This runs once during the upgrade and needs no action.
Creating a Plan
Create opens the New Limit Plan dialog:
- Name and Description — for example "Partner Limits", and who the plan is for.
- What to Limit — the plan type: API Request Count ("Request limits per API and endpoint.") or AI Token Limit ("Token and USD limits per LLM Gateway, model and provider."). The type cannot be changed later.
Save creates the plan and opens its page, where you add the limits and the target audience. A new plan is active, but it limits nobody until it has limits and a target audience.
A plan has one name. The Turkish label shown in the portal and in reports is that same name. A plan that already had a distinct Turkish name keeps it until the plan is saved again.
Duplicate (in the "⋯" menu) copies the plan's limits into a new plan. The Target Audience is not copied.
The Plan Page
The header of the plan page shows the plan's name, its status (Active or Inactive), its description and, for a profile owned by a subscription plan, the Subscription plan badge. The breadcrumb holds Back, the question-mark icon that opens the How to Read guide, the Variable icon, and the "⋯" menu: Activate or Deactivate under Status, Export and Duplicate under Transfer, Audit under History, and Delete last. The page has five tabs:
| Tab | What it holds |
|---|---|
| Definition | General information (name, type, status, last update, description), advanced settings — including what happens when a limit is reached — and a How it works summary. |
| Target Audience | The callers the plan limits. |
| API/Endpoint Limits (API Request Count) or AI Limits (AI Token Limit) | The limits per API, endpoint, API group, LLM Gateway, model or provider. |
| Conditions | A request condition that decides which requests the plan counts. |
| Error Message Customization | The messages returned when a limit is exceeded or the target audience rejects a caller. |
Each card has its own Configure button that opens a side drawer. On an active plan, saving a drawer first lists the changes and then applies them on the gateways at once ("Saved. It applies on the gateways now."). On an inactive plan, the changes are saved and apply once the plan is activated.
Limits Per Target
A plan holds one or more limits, and every limit names its target. A plan has no limit of its own that covers all the requests of an identity.
- API and Endpoint Limits (API Request Count) — a separate limit for one API, endpoint or API group. Each row is counted on its own.
- LLM Gateway, Model and Provider Limits (AI Token Limit) — a separate limit for one LLM Gateway, one model or one provider. Each row is counted on its own. Choose the Target Type (LLM Gateway, Model or Provider), then the target.
A call or request is counted in every row that covers it. The first limit that fills stops the request. For example, a Payments API limit of 600/min and a Payments API POST /payments limit of 60/min mean that a consumer cannot send more than 60 payment requests a minute, and all its requests to the Payments API together cannot pass 600.
When an API proxy or API proxy group is deleted, the plans' limits on it (including its endpoint limits) are removed, and active plans are updated on the gateways. The API proxy delete confirmation lists the plans that lose a limit. A limit whose record was deleted is shown with a Deleted badge and does not apply. Open the limit and delete it.
Earlier versions let a plan hold one limit for everything an assignment covered. On upgrade, such a limit is moved into the plan as one limit per target that the plan's assignments name, with the same values. An assignment on all APIs (or all AI traffic) names no target, so the old limit stops applying to it; add the API or AI limits that plan needs. Counters now count under the target of their limit, so the current minute and day windows restart once.
Scope of a row. For an API row you pick the project, the API or API group, an Environment and the endpoints: All endpoints of the API (one counter for every endpoint), Select endpoints (each selected endpoint has its own counter), or Select an endpoint (only that endpoint). A group limit counts the total of the requests to the group. The API list also includes LLM Gateways, so you can limit the request count of an LLM Gateway in an API Request Count plan (its token, USD and call-count use is limited in an AI Token Limit plan). An API row can also show an API total (all endpoints). For an LLM Gateway row of an AI Token Limit plan you pick the project, the LLM Gateway and optionally an environment; a model or provider row is not tied to a project.
One model of one provider. A model limit names one model of one LLM provider: the drawer asks for the Provider first and lists only the models of that provider. The gateway counts only the traffic that provider's model served. When a failover moves a request to another provider, the usage is counted for the model of the provider that served it. A model limit accepts only a provider that lists the model; a provider cannot remove a model while a plan limit or a live assignment names it. On upgrade, an older model limit that named only a model ID is bound to the single provider in the plan's scope that lists the model; if there is no such provider, or there is more than one, the limit is removed. Counters of the changed limits start a new window.
The model list shows the access state of each model as a badge. ACL (N) means the model has an access list of N identities; the limit then counts only their requests. ACL (0) means the access list is on and empty; no identity can call the model. Off means the model is switched off; no identity can call it. The access note of the chosen model is also shown under the field.
Values per environment. Each target holds one value per environment. The All environments value is the default. An environment-specific value replaces the default in that environment; the two are not added. If a target has no default, it has no limit in the environments that are not listed.
The screen warns when a row can never fill because a lower limit that covers it fills first.
Token, USD and Request-Count Limits
An AI Token Limit row holds any mix of these limits, each with a minute, hour, day and month field:
| Limit | Fields | Notes |
|---|---|---|
| Tokens | Tokens/Minute, Tokens/Hour, Tokens/Day, Tokens/Month | Whole numbers. |
| Cost | USD/Minute, USD/Hour, USD/Day, USD/Month | USD/Minute accepts up to 4 decimals (for example 0.0025); the other USD fields accept 2 decimals. Needs model prices, see USD Limits Need Model Prices. |
| LLM calls | Requests/Minute, Requests/Hour, Requests/Day, Requests/Month | In the Request Limits group of the Add Limit and Edit Limit drawers. Each request counts as one call; the minimum is 1, and a daily limit cannot exceed its monthly limit. |
A row needs at least one limit. Hard Cap (%) and Alert Thresholds (%) sit in their own Thresholds group of the drawer and apply to the token, USD and request-count limits of that row alike. The USD group stays named Budget (USD), because those fields are real money budgets. A limit chip shows the value as, for example, "0.5 USD / min" or "1,000 requests / day". The unit list of the general limit for callers outside the target audience (see Callers Outside the Target Audience) includes the request-count units as well.
Call-count limits are counted by the gateway under their own counters, never under the token counters, in UTC calendar windows. When one is reached, the call gets HTTP 429 with the same error code as a token limit (ERR-263), customizable on the plan's Error Message Customization tab. They are counted only for plan limits: the Token Rate Limit policy refuses a request-count limit when you save it. Call-count counters do not appear on Quota Usage & Alerts.
Advanced Settings
The defaults are enough in most cases. The Advanced Settings card on the Definition tab opens a drawer whose first part is When a Limit Is Reached.
When a Limit Is Reached sets what happens to a request that hits a limit:
| Plan type | Option | Meaning |
|---|---|---|
| Both | Reject the request | The caller gets HTTP 429. This is the right choice in most cases. |
| API Request Count | Let it pass, only count | The request passes. The overrun shows only in reports. |
| AI Token Limit | Let it pass, only alert | The call passes and an alert is raised. |
| AI Token Limit | Switch to a cheaper model | When the limit is reached, calls go to the chosen Model to Switch To, which is required. |
| AI Token Limit | Fail over | When the limit is reached, the backup provider is used. A backup whose own limit is full is skipped and the next backup in the chain is used. If no backup can be called, the request is rejected with HTTP 429. It is not sent to the over-budget primary. |
Let it pass, only count exists for the case where the plan backs a billed overage rather than a hard stop — see Referenced by a Portal Subscription Plan below.
The other settings of the drawer:
| Setting | Meaning | Plan type |
|---|---|---|
| Valid From / Valid Until | Optional validity window of the plan. Leave Valid Until empty for no end date. | Both |
| If the Counter Store Is Unreachable | Reject the request or Let the request pass when the counter service cannot be reached. | Both |
| Connection Timeout (s) | Maximum time to wait when connecting to the counter service. | Both |
| Remaining Limit in Response Headers | Show the remaining limit in response headers (RateLimit-Remaining, RateLimit-Limit, RateLimit-Reset, X-RateLimit-Type). An API Request Count plan also adds X-RateLimit-Identity. This is a select with three options: Inherit from the assignment (default), Shown and Not shown. With Inherit from the assignment, the setting of the assignment that adds the plan to the identity applies, and the plan card shows Assignment's setting applies. With Shown or Not shown, the plan decides. | Both |
The alert thresholds and the hard cap are not plan-wide settings: every AI limit has its own, in the Thresholds group of its drawer. Alert Thresholds (%) are values from 1 to 99, ascending, and the default is 50, 80 and 90. Hard Cap (%) is from 1 to 100; at this percentage of the limit, the action in When a Limit Is Reached starts, and the default, 100, means when the limit is full.
On an AI Token Limit plan, the headers show the limit with the smallest share left on this request. Token limits and call-count limits show in the headers. USD limits do not, because they are not a count of tokens or calls. When a limit is full, RateLimit-Remaining is 0 on the 429 response. RateLimit-Reset is the number of seconds until the window ends; on a monthly window it can be longer than one day. The LLM Gateway protection of the Token Rate Limit policy does not add these headers. The headers come on single responses, streamed (SSE) responses and binary (audio, image) responses.
When one request has both an API Request Count plan and an AI Token Limit plan that show these headers, the response keeps the values of the AI Token Limit plan. The headers do not select the stricter of the two plans. The unit of the number in the headers depends on the limit: tokens for a token limit, calls for a call-count limit.
The plan's own If the Counter Store Is Unreachable and Connection Timeout (s) settings win over the cache settings of the assignment (Action on cache connection error and Cache connection timeout (seconds)). The Token Rate Limit policy has its own Fail Open on Cache Error setting for the LLM Gateway Limit. It does not apply to plans.
The plan's custom error messages are set on the Error Message Customization tab. For an AI Token Limit plan this includes the message returned when the counter store cannot be reached and the plan rejects (HTTP 503, ERR-307).