Limit Plans

Licensing and Permissions

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.

Plans from earlier versions

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.

Known limitation

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

Conditions and Error Messages

The Conditions tab holds a request condition. The plan counts and blocks only the requests that meet the condition; other requests are not limited by this plan. Leave it empty to apply to every request.

The Error Message Customization tab holds the messages returned when a limit is exceeded or when the target audience rejects a caller. It is available on both plan types, AI Token Limit included. When it is left at its defaults, the platform-wide messages of the Error Messages screen are used.

Overlapping Plans

An identity can have several plans, and each plan counts on its own. There is one restriction: two plans that are counted the same way for one identity cannot limit the same API, endpoint or LLM Gateway. The screens enforce this with an Overlaps badge, and the server rejects a conflicting plan.

• On the plan page, a limit row that would overlap another plan of an identity on this plan is blocked ("You cannot limit this here."). A limit that overlaps only in some environments or for some HTTP methods can be added for the remaining ones.
• On the Limits tab, a plan that overlaps a plan the identity already has is disabled in the Add Limit Plan list, and the tooltip names the reason.
• When the overlap depends on request conditions, the screen only warns (Check conditions): make sure the two conditions do not match the same request.

If you need a different limit for the same traffic, create a separate plan and add it to a different set of identities.

Target Audience

The Target Audience tab sets who the plan limits. This works the same way for both plan types, AI Token Limit included.

A caller is in the target audience if it is a selected identity or matches a condition. A caller that fits both is counted once, and a selected identity uses its own counter. An identity can also get the plan from its own Limits tab; it is then in the audience as well.

The tab shows a summary of the audience. A plan with an empty audience waits in the catalog; it can still be picked from an identity's Limits tab.

Selected Identities

Under Selected Identities you add organizations, consumers, applications and API clients with Add Identity: choose the identity type, narrow the list by name (by client ID for API clients) and by organization, and tick the identities. For consumers you can also search by full name and by e-mail, and the table shows both. The list of selected identities shows the name, type and organization of each identity. For an organization, a consumer or an application, Counted As sets how the identity is counted — see The Limits Tab.

Callers Matching a Condition

Under Callers Matching a Condition the plan also limits callers that are not selected one by one. Choose Identify By:

Identify By	How the caller is recognized
Authentication	The username of the consumer, or the client ID of the API client, that the authentication policy resolved.
Request Variable	The value of the variable you select, read on each request.

Then describe the callers with rows. The rows and the regular expressions are joined with OR:

• Values — type a value and press Enter, paste a list (a#b#c, a,b or one per line), or use Import CSV. A CSV file adds every cell; a first row "value" is skipped.
• Regular expressions — each matching identity is counted on its own. A capture group makes the identities that share it count together: with team-blue-1 and team-blue-2, the group counts them under one shared counter. In Counted as, choose Each identity on its own or Group 1 (shared). The expression is searched in the identity; use ^ and $ to match the whole identity.

When Identify By is Request Variable, selected identities cannot be added next to the condition. Choose Authentication to select identities.

Callers Outside the Target Audience

This setting decides what happens to callers the plan does not cover:

Option	Meaning
Not affected	The default. Other callers are not limited by this plan.
Rejected (403)	Every other caller gets HTTP 403. When only identities are selected, this lets only the selected identities through.
General quota (General limit on an AI Token Limit plan)	Other callers share a quota or budget with its own limits. One quota for all (One limit for all) counts them together; Separately per identity gives each its own counter.

The setting is evaluated together for all plans with a condition on the same API (or LLM Gateway, model or provider).

Applying Changes

A saved target audience applies at once on an active plan. On an inactive plan it is saved and applies once the plan is activated.

Plan Status: Activate and Deactivate

A plan has no deploy step and keeps no revisions: what you save is what the gateways apply. A plan is in one of two states:

Status	Meaning
Active	Its limits apply on the gateways; every save reaches them at once. A new plan is active.
Inactive	The plan limits nothing until it is activated.

Activate and Deactivate are in the Status group of the plan page's "⋯" menu.

• Activate asks for confirmation; the plan's limits apply again on every gateway, for every identity that holds the plan.
• Deactivate stops the plan's limits on every gateway right away; requests are no longer counted or blocked by this plan. The dialog shows how many live assignments stop applying the plan. The limits, the assignments and the counters are kept, so Activate brings the same limits back. Counters are not reset: after activation, the limits continue from the current usage. You confirm by typing the plan name.

Delete

• Delete — you confirm by typing the plan name. An active plan is deactivated first, so its limits stop on every gateway. The live assignments end, draft assignments are deleted, the default limit plan settings that name the plan are removed, and the plan's information, limits, conditions, error message customizations and advanced settings are deleted. The dialog shows the counts. This cannot be undone.

The Limits Tab

A plan reaches an identity through that identity's Limits tab. The tab exists on an organization, a consumer, an application and an API client. A section for each plan type (AI Token Limit, API Request Count) lists the plans that apply to the identity.

Each plan on the tab is shown as a card with the plan name (a link to the plan), the plan's status — Active or Inactive — how it is counted, and badges such as the source of the assignment and Overlapping limits. The card shows the plan's definition only. It does not show usage — see Where to See Usage.

An identity can have several plans of one type, and each plan counts on its own. A different limit means a separate plan.

Adding and Removing Plans

Add Limit Plan lists every plan of the type. A plan that cannot be added is disabled, and the tooltip gives the reason (for example, an overlap, or the plan is already applied). For an organization and a consumer you also choose Counted As. It cannot be changed afterwards; to change it, remove the plan and add it again.

Counted As for an organization:

Option	Meaning
Organization total	One shared counter for everyone under the organization, including the API clients of its consumers and applications.
Each API client	Every API client under the organization that has no assignment of its own gets the plan with its own counter.
Each consumer	Every consumer and application under the organization without its own assignment gets the plan with its own counter.
Each sub-organization and the direct members	Every sub-organization without its own assignment gets the plan with its own counter, and counts its own subtree. The organization's own direct members (not those of its sub-organizations) share one counter of the organization.

Counted As for a consumer: Consumer total (one counter; its API clients are in the consumer's total and in the totals of the organizations above) or Each API client. An application is counted like a consumer (Application total).

The "Each …" options also cover identities added later.

Add and Apply adds the plan to the identity and puts it in force at once ("Limit plan added and in force."). If the plan is inactive, the identity gets it now and its limits apply once the plan is activated. An assignment stored as a draft elsewhere shows an Apply button on its card.

Remove stops the plan from applying to this identity immediately. The plan itself is not deleted and still applies to other identities. You can enter a reason. The Removed Limit Plans table lists the plan, type, start, end and reason. If you add the same plan again, it starts with a new counter.

A plan added by an administrator from the Administration menu carries the Assigned from Administration badge; only a system administrator can remove it.

Inherited Limit Plans

Inherited Limit Plans lists plans that an organization or a consumer above the identity applies to the identities under it with an "Each …" option. The list is read-only. The identity gets the nearest one. When the identity's own assignment applies to a request, the own assignment is used for that request instead.

Bulk Assignment

Adding a plan to one identity at a time does not scale once there are thousands of identities. Bulk Assignment adds one plan to many identities in a single run.

Reach it from the Bulk assignment button of the Limit Plans screen; the button is shown to users who can create plans. Under Administration → Identity Management → Limit Plans, the plans of the administration catalog are assigned to the identities of every project; in the project menu, the project's own plans and the shared administration plans are assigned to that project's identities. The Back button returns to the plan list. The screen has two tabs: New Assignment and History. A three-step flow builds a run:

1. Limit Plan — pick the plan. Every plan is listed; an inactive plan applies once it is activated. Limits, targets and error settings come from the plan; they cannot be changed on this screen.
2. Identities — choose the identity type (Consumers, API Clients, Applications or Organizations), narrow the list with filters, and select the identities. Ticking an organization also covers its sub-organizations. You can tick at most 5,000 identities one by one; for more, use Select all … that match the filter, which selects the whole filtered population in one click (identities added after the start are not included). Identities that already have this plan cannot be selected. When the identity type is Organizations, Consumers or Applications, you also choose Counted As: the total option (Organization total, Consumer total or Application total; one counter for each selected identity) or the option that fits the identity type among Each API client, Each consumer and Each sub-organization and the direct members (every identity of that kind under the selected identity without its own assignment gets the plan with its own counter).
3. Review and Start — the screen shows how many identities will get the plan, and how many already have it (they are skipped). The numbers are an estimate for large selections.

Under What happens to the other limit plans? you choose how identities that already have another plan of the same type are handled:

Option	Meaning	Default
Keep them	The new plan is added next to the current plans. The other plans and their counters do not change.	Yes (recommended)
Replace them with the new plan	The other plans of the same type and the same Counted As mode of these identities are removed. The counters of the new plan start from zero.	—

An optional Validity sets a start and an end date; by default the plan starts now and does not expire.

Start Assignment queues the run. It runs in the background, and you can leave the page.

History

The History tab lists every run with its start time, plan, identities, result (added, removed, restored, skipped, failed), status and who started it.

Status	Meaning
Queued	Accepted, not yet picked up.
Running	Actively processing.
Success	Every identity was processed with no failures.
Partial	Finished, but at least one identity failed.
Failed	The run could not complete.
Cancelled	Stopped by an operator with Stop.
Interrupted	The node running it stopped responding mid-run.

Runs recorded by an older version may still show License revoked, a state this version no longer produces.

• Details lists the skipped and failed identities with the reason for each.
• Stop asks a running run to stop at its next step; what was already written stays.
• Retry Failed starts a new run over only the identities the run failed on.
• Roll Back removes the plan from the identities the run added it to, and brings back the old plans the run removed (their counters restart, as with any replacement). The rollback is added to History as a new record. A confirmation comes first.

An interrupted run is resumed with Retry Failed. If writing the new assignment fails during a Replace or a rollback, the engine puts the old assignment back rather than leaving the identity with no limit; if even that fails, the row says the identity has no limit of this type now, and Retry Failed is the recovery.

Working Together With Your Existing Limits

API Request Count: an existing Rate Limit Control List or an API Proxy ACL/API Proxy Group ACL quota/throttling setting is no longer applied by the gateway — on upgrade, every such legacy limit was converted into a limit plan and assignment, so the ceiling itself carries over; only the mechanism enforcing it changed. See Legacy Limits Migrated at Upgrade below for exactly what moved and how.

AI Token Limit: the Token Quotas screen and the organization, application, project and platform budgets it saved are removed. Apinizer did not convert them. Recreate each limit as a plan, or as LLM Gateway Protection on the Token Rate Limit policy. See Removed AI Budgets below.

Enforcement

API Request Count

An active plan enforces for real. The gateway counts a request for every limit that covers it, and the first limit that fills stops the request. A plan that identifies callers by Authentication only applies to traffic that runs through an authentication policy, and treats an unauthenticated caller as outside its target audience. A plan that identifies callers by a Request Variable needs no authentication policy.

Per window:

• Granted — the request proceeds; the response gets the statistics headers if Remaining Limit in Response Headers is on.
• Exceeded, Reject the request — HTTP 429 with Retry-After; the error is a throttling error (second/minute windows) or a quota error (hour/day/month windows), customizable on the platform-wide Error Messages screen and on the plan's Error Message Customization tab. The Retry-After value is capped at a platform-wide ceiling (1 day by default, changeable with the apinizer.limit.retryAfterClampSeconds JVM system property on the Worker) rather than reporting the full window — this applies to an API Request Count and an AI Token Limit block alike.
• Exceeded, Let it pass, only count — the request is counted and let through; nothing is blocked.
• Counter service unreachable — the plan's If the Counter Store Is Unreachable setting: Reject the request or Let the request pass.

Observability: a Prometheus counter apinizer_limit_typed_decisions_total{family, outcome} (outcome: granted / blocked / count_only / cache_error_continue / cache_error_fail / out_of_target_block) tracks every enforcement decision.

AI Token Limit

An active plan is enforced on every AI request in its target audience, with or without the Token Rate Limit policy. The policy limits the LLM Gateway as a whole; plans limit the callers. Deleting or deactivating the policy does not stop plans.

• Who is limited. For a plan on a consumer or an API client, the gateway needs the caller's identity: an authentication policy on the proxy, or recognition by a Request Variable.
• What is counted. A call is counted in every limit row that covers it. The first limit that fills stops the call. Each target row has its own counter. A model row counts only the traffic served by the model of its provider; after a failover, the call is counted for the provider that served it.
• Environment values. The value of one environment replaces the All environments value in that environment; they are not added.
• Reservation. At the start of a request, the estimated tokens are reserved. When the response ends — streamed or not — the reservation is corrected with the real usage. If every provider fails, the reserved amount is released.
• Counters. Counters live in the shared cache service, so every worker uses the same counter, and a worker restart does not reset them.
• Windows are aligned to the UTC calendar: they renew at the start of each minute, hour, day (00:00 UTC) and month.
• Call-count limits. Each request counts as one call against the Requests/Minute, Requests/Hour, Requests/Day and Requests/Month limits of every row that covers it; the hard cap percentage applies, and the plan's action applies when one is reached. These counters are kept apart from the token counters.
• USD per minute. The cost of each call is counted in the current UTC minute. The hard cap percentage applies. When the limit is exceeded, the plan's action applies. With Reject the request, the response is HTTP 429 and Retry-After is the number of seconds left to the end of the minute. Usage reports and alarms do not show minute windows. The per-minute USD counters are kept only in memory and are not saved to the database. When you upgrade, upgrade the Cache servers before the Workers.
• When a limit is reached, the plan's action applies: Reject the request (HTTP 429 with Retry-After — the seconds left until the window ends, capped at 86,400 by default), Let it pass, only alert, Switch to a cheaper model, or Fail over. If no cheaper model is defined, the provider does not allow it, or the consumer has no access to that model, a Switch to a cheaper model request is rejected with HTTP 429.
• Alerts. When an alert threshold is crossed, or a call passes under Let it pass, only alert, the traffic record is marked and the event shows in the Active alerts panel of Analytic → Dashboard (AI view). Nobody is notified automatically — see Token Rate Limit Policy.
• Counter store unreachable. The plan's If the Counter Store Is Unreachable setting decides. See Advanced Settings.
• Several limits. A request must pass every plan that covers it, and the LLM Gateway Limit of the Token Rate Limit policy. The first limit to fill stops the request.

USD Limits Need Model Prices

A USD limit, including USD/Minute, meters only models that have an input price ("price per million input tokens") in the provider's Models section. A model without a price counts as 0 in cost reports, so a USD limit does not meter it and never cuts it off. Apinizer does not refuse to save such a limit.

A call that runs several model turns (for example, an agentic call with tool turns) is counted with the price of the model that served each turn.

Set an input price for every model that the USD limit must cover, or use a token limit instead.

The same applies to LLM Gateways that use Use the client's model: the client can request any enabled model of the routed LLM provider, so a USD limit meters only those of them that have a price. See USD limits need model prices for details. A model that is not on the provider's list has no price and is never metered; see Models That Are Not on the Provider's List.

The "Rate Limit" Badge on Develop

The Rate Limit badge shown on an API proxy's Develop screen is computed only from the plans currently covering the proxy. Clicking it opens a dialog listing every active assignment covering this proxy; each row names its subject and, when narrowed, the proxy or proxy group name.

A row whose subject no longer exists is marked Deleted consumer (or application, organization, API client) instead of showing a bare identifier, and that row carries its own End action, available to anyone who may manage limits.

Assignments left over from an earlier version

On upgrade, Apinizer ends every assignment whose subject no longer exists and records the reason as The subject no longer exists. The same check runs again each night, so an assignment orphaned later — by an import that replaced a record, or by a manual database correction — is closed on its own rather than staying in force.

Reports and Alerts

A counter attributed to a Consumer (or an API Client migrated from one) is folded into that consumer's existing counters, shown under the Quota Usage & Alerts report's existing Plan type, and caught by whatever Alert Definition already watches that consumer's Plan-type counters.

A counter attributed to any other subject (an organization, an API proxy or a rule assignment) keeps its own counter type instead — it is shown labeled Other in the report, but only once Show other counters is turned on (off by default). No pre-existing Alert Definition fires on it: an alert rule written before these limits existed must not silently start watching them. Alert notification text that does reference it labels it Rate Limit. Create a dedicated Alert Definition if you want to be notified.

Where to See Usage

The Limits tab does not show usage; it shows what each plan defines. Usage is shown here:

• Quota Usage & Alerts (Identity Management → Quota Usage & Alerts) — the usage of the counters, AI token and AI cost rows included. See Quota Usage & Alerts.
• Reports → Metrics (AI view), Cost & Consumers tab — the cost chart. It shows the cost of the month so far and has no budget line. See Reports and Analytics.

A Quota Usage alert rule evaluates AI counters only if AI Token and/or AI Cost is selected in the rule's counter types. With an empty list, the rule covers the gateway request counters only.

Error Codes

When a plan blocks or rejects a request, the caller sees one of these answers. The How to Read guide of the plan page lists them too.

HTTP code	When
429	A limit is reached. The Retry-After header gives the wait time. For an AI Token Limit plan the error code is ERR-263.
403	The caller is outside the target audience of a plan, and Callers Outside the Target Audience is Rejected (403). For an API Request Count plan the error code is ERR-251.
503	The counter store cannot be reached and an AI Token Limit plan is set to Reject the request. The error code is ERR-307.
400	The variable of a condition is missing from the request, so the caller cannot be identified. For an API Request Count plan the error code is ERR-252.

All messages are customizable on the Error Messages screen and on the plan's Error Message Customization tab. The default body of the AI Token Limit 429 answer is shown in Token Rate Limit Policy.

If a limit does not work, check in order:

1. When Identify By is Authentication: does the API proxy have an authentication policy?
2. Is the plan active?
3. Is the plan on the identity's Limits tab?
4. Does the limit point at the right API and endpoint?

Legacy Limits Migrated at Upgrade

When you upgrade to a version where the legacy API Request Count path is retired (see Working Together With Your Existing Limits and Enforcement above), every legacy API Request Count limit is converted into a limit plan and assignment automatically, before the Manager accepts requests. This section describes what that conversion does.

Legacy limits migrated at upgrade

On the upgrade, every legacy Rate Limit Control List rule and every API Proxy ACL/API Proxy Group ACL throttling/quota setting is converted into a limit plan and assignment — the gateway no longer reads either legacy source at all. Afterward, expect to see plans in your catalog that are named after the API and the limits they hold (for example "Orders · 200 requests/day") or after the control list they came from. A plan does not say that it came from the upgrade. The counters of the migrated API Request Count assignments start at zero.

Sources

• Every environment-scoped throttling and quota setting on an API Proxy ACL or API Proxy Group ACL row.
• Every Rate Limit Control List record. The records themselves stay readable on the read-only RLC screen.

Plan Creation

Every plan is an API Request Count plan, active, and holds limits that name their API:

Source	Plan
API Proxy ACL / API Proxy Group ACL row	One plan per row. Each environment's throttling and quota become a limit of the plan on the row's API proxy (or API proxy group) in that environment. Rows with the same limits on the same API share one plan, so thousands of legacy rows typically converge on a handful of plans. The plan is named after the API and its limits, for example "Orders · 200 requests/day".
Rate Limit Control List	One plan per list, named after the list and keeping its description. Each endpoint rule becomes a limit of the plan on that endpoint — or on the API proxy or API proxy group, when the rule was written for every endpoint. If the rules of one list read the identity from different variables, the list becomes one plan per variable, and the extra plans carry the variable's name. A list with no endpoint rule limited nothing, so no plan is created.

Window Mapping

Legacy field	Window
Throttling, 1 Second / 1 Minute interval	Second / Minute window
Quota, 1 Hour / 1 Day / 1 Month interval	Hour / Day / Month window
Both throttling and quota on the same row	Both windows, on the same plan

Window Type (Fixed/Sliding), Counting Mode and Limit Change Action are carried over unchanged for each window.

Enforcement Posture

• If the Counter Store Is Unreachable: Reject the request if either the throttling side or the quota side of the legacy row rejected. When the environments of one row differ, the plan carries one setting for all of them: reject if any environment rejected.
• Connection Timeout: the larger of the legacy timeouts.
• Remaining Limit in Response Headers: carried over if any environment set it.
• A Rate Limit Control List's condition, its position in the request flow (execution order), and its own custom error message, content type and HTTP status code are carried over onto the resulting plan.

Assignment

Every migrated row becomes an assignment that is active, with its own end date set to the row's expiry date, if it had one.

Legacy row	Who is limited
API Proxy ACL / API Proxy Group ACL row	The Consumer itself — the same whether the Consumer was later migrated to an API client or stayed Consumer only; when its twin belongs to a portal application, the API client (its client id) instead. The plan's limits name the API and the environment.
Rate Limit Control List	A list that reads the identity from authentication: each listed Consumer is a selected identity of the plan, one assignment each. Any other list: one assignment that carries the list's whole audience as a condition.

A Rate Limit Control List's Target Consumers list was, in legacy behavior, that rule's own allow list: an identity missing from it received the rule's out-of-target action instead of the rule's own ceiling. The migration keeps that shape: the listed Consumers are in the plan's target audience, and a Consumer left off the list falls through to the rule's out-of-target action, the same as it did before the upgrade. When the list names Consumers, the gateway used their usernames and ignored the list's separate identity values; the plan keeps that behavior.

A Rate Limit Control List's Target Audience conditions, its equality-based target identity values (not already covered by the Target Consumers list) and its regular expressions become part of the same audience: the identity source (auth-resolved or variable), the out-of-target action (Block, or a general quota), and the general quota itself (Total/Per identity, with its own window) all carry over. When the out-of-target action is a general quota but its quota fields were left empty, the rule's own limit is carried over as the general quota instead — the same fallback the legacy runtime applied. A list that names nobody keeps its out-of-target action for every caller, as before; review such a plan.

AI Budgets

History

This section describes the 2026.09.2 upgrade. The AI Budget Source setting and the remaining entity budgets were removed later, in 2026.10.0. See Removed AI Budgets.

A consumer-level AI token budget is migrated the same way, from a different source and into a different plan type:

• Source: the environment-level Enable AI Token Budget setting (and its budget values) on an API Proxy ACL/API Proxy Group ACL row.
• Plan: rows sharing the exact same budget body are folded the same way API Request Count rows are — one AI Token Limit plan per distinct body, active. The 2026.09.2 upgrade named such a plan Migrated AI_TOKEN_BUDGET #<checksum>; the 2026.10.0 upgrade renames it after its limits, for example "AI budget 50000 tokens/day".
• Assignment: subject is the Consumer itself — the same twin the API Request Count migration above targets — or, when that Consumer's migrated API client belongs to a portal application, the API client instead; scope One API Proxy + Environment, matching the row's own proxy and environment; source Migration; end date the row's own expiry, if it had one.
• No counter reset: unlike every other migrated assignment, this one is counted under the same counter the legacy budget already used, so in-window consumption carries over rather than restarting at zero. A Consumer later migrated to an API client keeps sharing that same counter with its legacy record.

In 2026.09.2, the row's AI Budget Source field only decided whether the organization-level AI budget chain applied to that Consumer on that proxy. That field is removed. To stop the migrated assignment, remove the plan on the identity's Limits tab.

Not every enabled row is carried — see the AI-specific outcomes in Not Migrated (Reported Only) below. A row whose AI Budget Source was Organization is the notable case: its own budget was never enforced even before this migration (only the organization chain applied to it), so nothing is lost by leaving it out — add a plan directly on the Limits tab if you want that Consumer to also carry its own ceiling. A row whose Consumer no longer exists is skipped and recorded as CREDENTIAL_MISSING, the same as a portal-derived or expired row is skipped and counted without being listed individually.

Not Migrated (Reported Only)

The following legacy items have no counterpart, are intentionally skipped, or are carried over with a caveat; each is recorded in the migration's audit ledger:

Legacy item	Outcome
A disabled Rate Limit Control List	The plan is created inactive, so it limits nothing, as before. Activate the plan to start its limits.
An expired row	Skipped
A row disabled for its environment	Skipped, recorded as ENV_DISABLED_SKIPPED
A row whose limit fields were left incomplete	Skipped, recorded as LIMIT_INCOMPLETE_SKIPPED
A Rate Limit Control List rule with no limit configured on it	Skipped, recorded as RULE_WITHOUT_LIMIT
A rule that names no API proxy, group or endpoint	Skipped, recorded as RULE_NOT_KEYED — the gateway never applied it
A row pointing at a deleted API, group, or endpoint	Skipped, recorded as RULE_TARGET_MISSING
An API Proxy ACL/Group ACL row with a different cache-error posture for its throttling side than its quota side	Both carried onto the plan as Reject the request, the stricter of the two, recorded as CACHE_POSTURE_MERGED
A rule audience whose out-of-target action is General quota but whose quota fields were left empty	The rule's own limit is carried over as the general quota instead, recorded as GENERAL_QUOTA_FALLBACK
A Rate Limit Control List with no consumers, no target identities, and no condition to migrate	The plan is still created and its out-of-target action applies to every caller, as before, recorded as EMPTY_AUDIENCE_KEPT
A regular expression of a list that does not compile	Not carried, recorded as INVALID_REGEX_DROPPED — it never matched
A portal-derived (subscription/product) row	Skipped — carried instead by the Subscription Plan assignment backfill; see Upgrading Existing Subscription Plans
A row's AI Budget Source set to Organization (2026.09.2 upgrade)	Not carried — see AI Budgets above; recorded as AI_LEAF_EXCLUDED_BY_SOURCE, information only, not a residual failure
Enable AI Token Budget on but the budget itself disabled or naming no ceiling (2026.09.2 upgrade)	Skipped, recorded as AI_BUDGET_INCOMPLETE_SKIPPED
A row with Enable AI Token Budget on but no API proxy named on it (2026.09.2 upgrade)	Skipped, recorded as AI_BUDGET_TARGET_MISSING

Re-running the migration is idempotent: an identity/scope pair that already has an active assignment from a previous run is left as-is, not written again.

Project and Platform Limits Removed

Version 2026.10.0 removed the Project and Platform Limits screen and the project and platform assignments. A limit plan can be assigned to a consumer, an API client, an application, an organization, an API proxy (LLM Gateway) or an audience rule. This holds for both types: API Request Count and AI Token Limit. The gateways no longer enforce project or platform assignments.

On upgrade, Apinizer does the following once, when the Manager starts:

• Every project and platform assignment that was not yet ended is ended. It is ended by system with the reason "Project and platform limits were removed in this version". No screen shows it any more. You can read it through the Management API or APIops. The gateways stop applying it.
• Every enabled AI Token Usage Percentage alarm with the Project scope is disabled. Apinizer keeps the alarm. Change its scope to LLM Gateway and enable it again. See Alarm.

The REST and Management API refuse a new project or platform assignment. A package import skips a project or platform assignment file, shows the notice "These limit assignments were NOT imported" and imports the rest of the package.

To limit a whole population, assign the plan to the consumers, API clients, applications or organizations, or use the Counted As choices of an organization.

Removed AI Budgets

Version 2026.10.0 removed the Token Quotas screen and every budget it saved:

• the organization AI budget;
• the LLM Gateway application budget and the anonymous budget of the LLM Gateway routing;
• the project (tenant) budget;
• the default budget and the default anonymous budget on the AI Gateway tab of System Settings;
• the AI Budget Source setting and the AI token budget per environment on an access row.

The upgrade removes the stored values. It does not convert them into plans. Recreate each limit:

Removed limit	Where to set it now
Limit for an organization, consumer, application or API client	An AI Token Limit plan, added on the Limits tab or in the target audience.
Limit for a whole project or the platform	Removed. See Project and Platform Limits Removed.
Limit for one LLM Gateway	LLM Gateway Protection in the Token Rate Limit policy.

Export packages and APIops requests that still carry the old fields are accepted. Apinizer ignores the fields and keeps the rest.

Referenced by a Portal Subscription Plan

An active, platform-scope plan can also be referenced from a portal API Product's Subscription Plan — the commercial plan a developer subscribes to — instead of, or alongside, being added by hand on the Limits tab. See API Product → Limit Profiles and → Typed Limit Binding for how this is configured and materialized on the product side; this section covers what happens on the limit side.

A Subscription Plan may reference at most one API Request Count plan and one AI Token Limit plan, each Off or a specific active plan. The referenced plan's overflow posture must agree with the Subscription Plan's own on-exceed setting — Block needs a plan that blocks, Continue & charge needs a plan that only counts (Let it pass, only count for API Request Count, Let it pass, only alert for AI Token Limit) — a mismatch is refused when the Subscription Plan is saved.

When a subscription of that plan is approved, one active assignment is created automatically for the subscribing application, per referenced type — sourced from the subscription rather than entered by hand, application-wide rather than tied to one API. Both a subscription-sourced API Request Count assignment and a subscription-sourced AI Token Limit assignment enforce for real.

An application can have only one such assignment per type. If a second, different subscription of the same application also references a plan for that type, the existing assignment is kept, and the operator approving the second subscription is asked to keep it or switch to the new plan. When a subscription that owns the assignment ends, it is handed over to another still-approved subscription of the same application that references the same type, if one exists, so coverage and accumulated usage are not lost; otherwise the assignment ends with it.

Upgrading Existing Subscription Plans

On upgrade, Subscription Plans that already carry quota or rate-limit numbers are converted automatically: a matching platform-scope API Request Count plan is created and the Subscription Plan is pointed at it, so nothing changes for existing subscribers. Subscriptions that were already approved before the upgrade do not receive their assignment automatically — a system administrator runs a one-time backfill (previewed by default, applied on request) to create it for the existing backlog. See API Product → Version Upgrade for the portal-side summary and the Limit Plans, Assignments & Defaults API reference for the backfill endpoint.

Next Steps

Token Rate Limit Policy

Protect an LLM Gateway with its own token and cost limit

Consumers

Review the API client lifecycle and the API Clients tab

Access Control and Roles

Configure who can view and manage the Limit Plans screens

API Product

Reference a platform Limit Profile from a Subscription Plan

Bulk Limit Assignment API

Preview, start, and monitor a bulk assignment run through the Management API

Limit Plans Management API

Create, update, and delete Limit Plans through the Management API

Limit Assignments API

Assign, replace, and remove individual Limit Plan assignments through the Management API