Chapter 114 min read

Limits on every level and postpaid organizations

Learn how the spend limits of LLM keys, users, teams, and organizations are held together for every request, how usage counts towards the levels above, who sets each level, and how postpaid organizations are billed.

Before a request goes upstream, the gateway holds its estimated cost on all of the following at the same time, and when the request ends it settles the actual cost on all of them together. If any one of them cannot take the hold, the request is refused, so the limit that applies is whichever has the least left:

LLM key limits: the usage of this key.
User limits: this member’s usage in the organization.
Team limits: the usage of the member’s team and of every parent team.
Organization limits: the usage of the organization and of every parent organization.
Prepaid organizations: the member’s Wallet balance and active packages.
Postpaid organizations: the organization’s Organization postpaid credit limit.

For example, with an organization limit of 1,000 and a team limit of 500, the members of that team can use at most 500 between them, even if a member’s wallet holds 10,000.

A request is held on every level at once; the level with the least left decides

CCHP

How usage counts towards the levels above#

Every amount a member spends counts towards the member, the member’s team and every parent team of it, and the organization and every parent organization of it. So:

A team’s usage includes the usage of all its sub-teams.
An organization’s usage includes the usage of all its sub-organizations.
An LLM key limit counts only that key’s usage.

A member's usage counts towards the teams and organizations above

CCHP

Who sets each level#

Level	Set by	Where
Organization limits	Platform super admins	Org management → organization settings → Shared organization limits
Default limits per member	Organization admins	Organization settings → Default limits per member
Team limits	Organization admins	Team details → Limits
User limits	Team admins of the user’s team (or a parent team), and organization admins	User details → Limits
LLM key limits	Organization admins and team admins	Key details → Settings → Limits
Billing mode and Organization postpaid credit limit	Platform super admins	Organization settings → Billing mode

Everyone else can only view these limits and their usage.

The limit types are 5-hour credits, Daily credits, Weekly credits, Monthly credits, and Total credits. Each level sets its own, and each type counts separately. A limit card shows what is used, what is left, and when it resets.

When a level’s limit is used up, the gateway returns HTTP 429 with error code 20003, and the message names the level and the limit type. Wait for that limit’s window to reset, or ask whoever sets that level to raise it.

Prepaid and postpaid#

The installer picks prepaid or postpaid when creating the first organization in the setup wizard, and for postpaid can set the organization postpaid credit limit at the same time. After that, only platform super admins change the billing mode, in the Billing mode section of the organization settings, and other new organizations are prepaid. In both modes, the limits on every level above apply at the same time.

Prepaid#

Members’ wallets and packages pay for requests. A request is admitted only when the available wallet balance plus the remaining package allowance covers the hold. Otherwise the gateway returns HTTP 402 with error code 20004.

Postpaid#

Requests are charged to the organization’s postpaid account. Members’ wallet balances and packages stay unchanged.
The organization’s requests in progress and settled costs this month (UTC calendar month, reset on the 1st) are its postpaid credit and cannot exceed the Organization postpaid credit limit. Over it, the gateway returns HTTP 402 with error code 20018. Without a limit there is no ceiling.
Members’ usage still counts towards the user, team, and organization limits.

On the Wallet page, members see the organization’s billing mode below Available balance. In a postpaid organization, it also shows how much of the organization’s postpaid credit is left this month.

Limits of providers and provider keys#

Provider and provider key limits are counted apart from the levels above. When a provider key cannot take the hold, the gateway uses another candidate. A provider’s usage is the total of all its provider keys.

What these limits count is set by platform super admins in Administration → System Management → Routing → Routing Quota, under Provider spend limits count, and can be set for an organization of its own:

Provider cost (default): the official price times the provider key, provider, and endpoint price multipliers. See Provider cost multipliers vs. user billing multipliers.
Amount billed to users: what the organization’s members pay.

Frequently asked questions#

My wallet has enough balance, so why does it say a limit is used up?#

One level’s limit is used up. The 429 message says whether it is the LLM key, member, team, or organization limit, and which type. Team and organization limits are shared by all their members, so other members’ usage uses them up too.

Requests of a postpaid organization return 402#

The organization’s postpaid credit for this month is used up. Ask a platform super admin to raise the Organization postpaid credit limit in the Billing mode section of the organization settings.